create_base_folium_map

class pyhelpers.viz.create_base_folium_map(gdf, center_method='bounds', fit_bounds=True, tiles=None, initial_tile_name=None, add_mini_map=True, **kwargs)[source]

Initializes a Folium map centered on the extent of a GeoDataFrame.

This function first calls get_base_map_center() to calculate the map center coordinates and re-project the data to EPSG:4326 (WGS84), which is required by Folium.

Parameters:

  • gdf (geopandas.GeoDataFrame) – Input GeoDataFrame containing the geographical features.

  • center_method (str) –

    The method used to calculate the map center.

    • 'bounds': Calculates the center based on the arithmetic mean of the bounding box corners (quickest method).

    • 'centroid': Calculates the true geometric centroid of the merged (union) geometry (most accurate, requires projection).

    • 'convex_hull': Calculates the centroid of the convex hull of all geometries (quicker than ‘centroid’ for complex data).

  • fit_bounds (bool) – Whether to automatically adjust the map view to fit the full extent of the data bounds. Defaults to True.

  • tiles (str | list[str] | None) – The tile layer(s) to use. Can be a string (e.g. 'CartoDB positron') or a list of strings for multiple tile layers.

  • initial_tile_name (str | None) – Optional custom name to display for the first (default) tile layer in the map’s Layer Control. If None, the default tile name is used.

  • add_mini_map (bool) – If True, a small inset map is added to the bottom-right corner using folium.plugins.MiniMap.

  • kwargs (dict) – Additional arguments passed to the folium.Map constructor.

Returns:

Tuple of (re-projected GeoDataFrame, Folium Map object).

Return type:

tuple[folium.Map, geopandas.GeoDataFrame]

Examples:

>>> from pyhelpers.viz import create_base_folium_map
>>> from pyhelpers._cache import example_dataframe
>>> from shapely.geometry import Point
>>> import geopandas as gpd
>>> df = example_dataframe()
>>> df['geometry'] = df.apply(lambda x: Point([x.Longitude, x.Latitude]), axis=1)
>>> gdf = gpd.GeoDataFrame(df, geometry='geometry', crs=4326)
>>> m, gdf_proj = create_base_folium_map(gdf, fit_bounds=False, zoom_start=7)
>>> m.show_in_browser()