CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-folium

Make beautiful maps with Leaflet.js & Python

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

vector-layers.mddocs/

Vector Layers

Geometric shapes and paths including polylines, polygons, circles, and rectangles with customizable styling, interactive features, and data integration capabilities.

Capabilities

Lines and Paths

Multi-segment lines connecting coordinate points with extensive styling options.

class PolyLine:
    """
    Create multi-segment lines connecting coordinate points.
    
    Parameters:
    - locations: list, coordinate pairs [[lat1, lon1], [lat2, lon2], ...]
    - popup: str or Popup, popup content for the line
    - tooltip: str or Tooltip, tooltip content
    - smooth_factor: float, path smoothing factor (default 1.0)
    - no_clip: bool, disable clipping to map bounds (default False)
    - color: str, line color (default 'blue')
    - weight: int, line width in pixels (default 3)
    - opacity: float, line opacity (default 1.0)
    - line_cap: str, line cap style ('butt', 'round', 'square')
    - line_join: str, line join style ('miter', 'round', 'bevel')
    - dash_array: str, dash pattern (e.g. '5, 5' for dashed line)
    - dash_offset: str, dash offset
    - fill: bool, fill the path (default False)
    - fill_color: str, fill color
    - fill_opacity: float, fill opacity (default 0.2)
    - fill_rule: str, fill rule ('evenodd' or 'nonzero')
    - bubbling_mouse_events: bool, bubble mouse events (default True)
    
    Returns:
    PolyLine instance
    """
    def __init__(
        self,
        locations,
        popup=None,
        tooltip=None,
        smooth_factor=1.0,
        no_clip=False,
        color='blue',
        weight=3,
        opacity=1.0,
        line_cap='round',
        line_join='round',
        dash_array=None,
        dash_offset=None,
        fill=False,
        fill_color=None,
        fill_opacity=0.2,
        fill_rule='evenodd',
        bubbling_mouse_events=True,
        **kwargs
    ): ...

Polygons

Closed shapes with fill and stroke styling, supporting complex geometries with holes.

class Polygon:
    """
    Create closed polygon shapes with customizable fill and border styling.
    
    Parameters:
    - locations: list, coordinate pairs for polygon boundary, or list of lists for polygons with holes
    - popup: str or Popup, popup content
    - tooltip: str or Tooltip, tooltip content
    - color: str, border color (default 'blue')
    - weight: int, border width in pixels (default 3)
    - opacity: float, border opacity (default 1.0)
    - line_cap: str, line cap style ('butt', 'round', 'square')
    - line_join: str, line join style ('miter', 'round', 'bevel')
    - dash_array: str, border dash pattern
    - dash_offset: str, border dash offset
    - fill: bool, fill the polygon (default True)
    - fill_color: str, fill color (defaults to border color)
    - fill_opacity: float, fill opacity (default 0.2)
    - fill_rule: str, fill rule ('evenodd' or 'nonzero')
    - bubbling_mouse_events: bool, bubble mouse events (default True)
    - smooth_factor: float, path smoothing factor (default 1.0)
    - no_clip: bool, disable clipping to map bounds (default False)
    
    Returns:
    Polygon instance
    """
    def __init__(
        self,
        locations,
        popup=None,
        tooltip=None,
        color='blue',
        weight=3,
        opacity=1.0,
        line_cap='round',
        line_join='round',
        dash_array=None,
        dash_offset=None,
        fill=True,
        fill_color=None,
        fill_opacity=0.2,
        fill_rule='evenodd',
        bubbling_mouse_events=True,
        smooth_factor=1.0,
        no_clip=False,
        **kwargs
    ): ...

Rectangles

Rectangular shapes defined by corner coordinates.

class Rectangle:
    """
    Create rectangular shapes defined by corner coordinates.
    
    Parameters:
    - bounds: list, bounding coordinates [[south, west], [north, east]]
    - popup: str or Popup, popup content
    - tooltip: str or Tooltip, tooltip content
    - color: str, border color (default 'blue')
    - weight: int, border width in pixels (default 3)
    - opacity: float, border opacity (default 1.0)
    - line_cap: str, line cap style ('butt', 'round', 'square')
    - line_join: str, line join style ('miter', 'round', 'bevel')
    - dash_array: str, border dash pattern
    - dash_offset: str, border dash offset
    - fill: bool, fill the rectangle (default True)
    - fill_color: str, fill color (defaults to border color)
    - fill_opacity: float, fill opacity (default 0.2)
    - fill_rule: str, fill rule ('evenodd' or 'nonzero')
    - bubbling_mouse_events: bool, bubble mouse events (default True)
    
    Returns:
    Rectangle instance
    """
    def __init__(
        self,
        bounds,
        popup=None,
        tooltip=None,
        color='blue',
        weight=3,
        opacity=1.0,
        line_cap='round',
        line_join='round',
        dash_array=None,
        dash_offset=None,
        fill=True,
        fill_color=None,
        fill_opacity=0.2,
        fill_rule='evenodd',
        bubbling_mouse_events=True,
        **kwargs
    ): ...

Circles

Two types of circular shapes: geographic circles with radius in meters, and pixel-based circle markers.

class Circle:
    """
    Create circles with radius specified in map units (meters).
    
    Parameters:
    - location: tuple, center coordinates [lat, lon]
    - radius: float, circle radius in meters (default 10)
    - popup: str or Popup, popup content
    - tooltip: str or Tooltip, tooltip content
    - color: str, border color (default 'blue')
    - weight: int, border width in pixels (default 3)
    - opacity: float, border opacity (default 1.0)
    - line_cap: str, line cap style ('butt', 'round', 'square')
    - line_join: str, line join style ('miter', 'round', 'bevel')
    - dash_array: str, border dash pattern
    - dash_offset: str, border dash offset
    - fill: bool, fill the circle (default True)
    - fill_color: str, fill color (defaults to border color)
    - fill_opacity: float, fill opacity (default 0.2)
    - fill_rule: str, fill rule ('evenodd' or 'nonzero')
    - bubbling_mouse_events: bool, bubble mouse events (default True)
    
    Returns:
    Circle instance
    """
    def __init__(
        self,
        location=None,
        radius=10,
        popup=None,
        tooltip=None,
        color='blue',
        weight=3,
        opacity=1.0,
        line_cap='round',
        line_join='round',
        dash_array=None,
        dash_offset=None,
        fill=True,
        fill_color=None,
        fill_opacity=0.2,
        fill_rule='evenodd',
        bubbling_mouse_events=True,
        **kwargs
    ): ...

class CircleMarker:
    """
    Create circles with radius specified in screen pixels (consistent size regardless of zoom).
    
    Parameters:
    - location: tuple, center coordinates [lat, lon]
    - radius: int, circle radius in pixels (default 10)
    - popup: str or Popup, popup content
    - tooltip: str or Tooltip, tooltip content
    - color: str, border color (default 'blue')
    - weight: int, border width in pixels (default 3)
    - opacity: float, border opacity (default 1.0)
    - line_cap: str, line cap style ('butt', 'round', 'square')
    - line_join: str, line join style ('miter', 'round', 'bevel')
    - dash_array: str, border dash pattern
    - dash_offset: str, border dash offset
    - fill: bool, fill the circle (default True)
    - fill_color: str, fill color (defaults to border color)
    - fill_opacity: float, fill opacity (default 0.2)
    - fill_rule: str, fill rule ('evenodd' or 'nonzero')
    - bubbling_mouse_events: bool, bubble mouse events (default True)
    
    Returns:
    CircleMarker instance
    """
    def __init__(
        self,
        location=None,
        radius=10,
        popup=None,
        tooltip=None,
        color='blue',
        weight=3,
        opacity=1.0,
        line_cap='round',
        line_join='round',
        dash_array=None,
        dash_offset=None,
        fill=True,
        fill_color=None,
        fill_opacity=0.2,
        fill_rule='evenodd',
        bubbling_mouse_events=True,
        **kwargs
    ): ...

Usage Examples

Multi-colored Path

import folium

# Create a map
m = folium.Map(location=[45.52, -122.67], zoom_start=13)

# Define path coordinates
path_coords = [
    [45.52, -122.68],
    [45.521, -122.679],
    [45.522, -122.678],
    [45.523, -122.677],
    [45.524, -122.676]
]

# Add styled polyline
folium.PolyLine(
    locations=path_coords,
    color='red',
    weight=5,
    opacity=0.8,
    dash_array='10, 5',
    popup='Walking Route',
    tooltip='5-minute walk'
).add_to(m)

m.save('styled_path.html')

Polygon with Holes

import folium

m = folium.Map(location=[45.52, -122.67], zoom_start=14)

# Outer boundary
outer_coords = [
    [45.520, -122.672],
    [45.524, -122.672], 
    [45.524, -122.668],
    [45.520, -122.668]
]

# Inner hole
hole_coords = [
    [45.521, -122.671],
    [45.523, -122.671],
    [45.523, -122.669], 
    [45.521, -122.669]
]

# Create polygon with hole
folium.Polygon(
    locations=[outer_coords, hole_coords],
    color='blue',
    weight=2,
    fill_color='lightblue',
    fill_opacity=0.4,
    popup='Building with Courtyard'
).add_to(m)

m.save('polygon_with_hole.html')

Circles with Different Radius Types

import folium

m = folium.Map(location=[45.52, -122.67], zoom_start=13)

# Geographic circle (radius in meters)
folium.Circle(
    location=[45.521, -122.671],
    radius=200,  # 200 meters
    color='red',
    fill_color='pink',
    fill_opacity=0.3,
    popup='200m radius circle'
).add_to(m)

# Pixel circle marker (consistent size at all zoom levels)
folium.CircleMarker(
    location=[45.523, -122.669],
    radius=15,  # 15 pixels
    color='blue',
    fill_color='lightblue',
    fill_opacity=0.7,
    popup='15px radius marker'
).add_to(m)

m.save('circles_comparison.html')

Data-driven Styling

import folium
import pandas as pd

# Sample data
data = pd.DataFrame({
    'location': [[45.520, -122.672], [45.522, -122.670], [45.524, -122.668]],
    'value': [10, 25, 40],
    'category': ['low', 'medium', 'high']
})

m = folium.Map(location=[45.522, -122.670], zoom_start=14)

# Color mapping
color_map = {'low': 'green', 'medium': 'orange', 'high': 'red'}

# Add circles with data-driven styling
for idx, row in data.iterrows():
    folium.CircleMarker(
        location=row['location'],
        radius=row['value'] / 2,  # Scale radius by value
        color=color_map[row['category']],
        fill_color=color_map[row['category']],
        fill_opacity=0.6,
        popup=f"Value: {row['value']}<br>Category: {row['category']}"
    ).add_to(m)

m.save('data_driven_circles.html')

Complex Multi-part Geometry

import folium

m = folium.Map(location=[45.52, -122.67], zoom_start=12)

# Create a feature group for related shapes
shapes_group = folium.FeatureGroup(name='Area Analysis')

# Main area polygon
main_area = [
    [45.515, -122.675],
    [45.525, -122.675],
    [45.525, -122.665],
    [45.515, -122.665]
]

folium.Polygon(
    locations=main_area,
    color='blue',
    weight=3,
    fill_color='lightblue',
    fill_opacity=0.3,
    popup='Study Area'
).add_to(shapes_group)

# Buffer zone around area
buffer_coords = [
    [45.514, -122.676],
    [45.526, -122.676],
    [45.526, -122.664],
    [45.514, -122.664]
]

folium.Rectangle(
    bounds=[[45.514, -122.676], [45.526, -122.664]],
    color='red',
    weight=2,
    fill=False,
    dash_array='5, 5',
    popup='Buffer Zone'
).add_to(shapes_group)

# Add connecting lines
connections = [
    [[45.520, -122.670], [45.522, -122.668]],
    [[45.522, -122.672], [45.520, -122.670]]
]

for line in connections:
    folium.PolyLine(
        locations=line,
        color='green',
        weight=2,
        opacity=0.8
    ).add_to(shapes_group)

shapes_group.add_to(m)
folium.LayerControl().add_to(m)

m.save('complex_geometry.html')

Install with Tessl CLI

npx tessl i tessl/pypi-folium

docs

core-mapping.md

data-visualization.md

index.md

interactive-features.md

plugins.md

utilities-styling.md

vector-layers.md

tile.json