Layers

All layers share the base accessor contract and common parameters — see BaseLayer below. Layers under Experimental import from deckgl_marimo.layers and warn on construction.

Base

deckgl_marimo._base.BaseLayer

Base class for all deck.gl layer wrappers.

Layers are plain Python objects that serialize to JSON specs via :meth:to_spec. They can also be used directly as widgets — passing a layer to mo.ui.anywidget() or displaying it in a notebook cell automatically wraps it in a :class:Map.

Accessors

Any parameter named get_* accepts one of the following forms:

• A constant (e.g. [255, 0, 0, 255] or 5.0).
• A column name string (e.g. "population") — looked up per row.
• A list of column names for vector accessors (e.g. ["lon", "lat"]).
• A callable f(row) -> value, materialized over the data at spec time.
• A :class:~deckgl_marimo.ColorScale instance (color accessors only).

Materialized callables and ColorScale require concrete data (DataFrame, list of dicts, etc.); URL data is not supported for these forms. See :class:~deckgl_marimo.Accessor, :class:~deckgl_marimo.PositionAccessor, and :class:~deckgl_marimo.ColorAccessor for the type aliases.

Parameters:

Name	Type	Description	Default
data	Any	Input data. Accepts pandas/polars DataFrames, GeoDataFrames, DuckDB Relations, list of dicts, GeoJSON dicts, or URLs.	None
id	str | None	Unique layer identifier. Auto-generated if not provided.	None
visible	bool	Whether the layer is visible.	True
opacity	float	Layer opacity (0-1).	1.0
pickable	bool	Whether the layer responds to pointer events.	True
auto_highlight	bool	Whether to highlight the picked object.	False
visible_min_zoom	float | None	Minimum zoom level (inclusive) at which the layer is visible. If None (default), no lower bound is applied.	None
visible_max_zoom	float | None	Maximum zoom level (inclusive) at which the layer is visible. If None (default), no upper bound is applied.	None
load_options	dict[str, Any] | None	Options passed to deck.gl's loaders.gl data loading system. Use this for full control over fetch configuration, e.g. {"fetch": {"credentials": "include", "headers": {...}}}.	None
fetch_headers	dict[str, str] | None	Convenience shortcut to set HTTP headers on the data fetch request. Equivalent to load_options={"fetch": {"headers": {...}}}. If both fetch_headers and load_options specify headers, the load_options headers take precedence.	None
basemap	str	Basemap style for standalone display (default "dark-matter").	'dark-matter'
center	tuple[float, float] | None	Initial map center as (longitude, latitude) for standalone display.	None
zoom	float	Initial zoom level for standalone display.	1.0
pitch	float	Initial pitch for standalone display.	0.0
bearing	float	Initial bearing for standalone display.	0.0
map_height	str	CSS height for standalone display.	'600px'
_unsafe_props	bool	If True, skip validation of unknown **props keys. Use only when passing through undocumented deck.gl props; subclass __init__ signatures normally cover the supported set.	False
**props	Any	Additional deck.gl layer properties in snake_case. Validated against the subclass's declared kwargs unless _unsafe_props is set.	{}

to_spec

to_spec()

Serialize to a JSON-compatible dict for the JS layer factory.

Returns:

Type	Description
dict	Layer specification with camelCase keys matching deck.gl API.

to_specs

to_specs()

Serialize to a list of JSON-compatible specs.

Composite layers override this to return multiple specs. Simple layers return a single-element list.

to_binary

to_binary()

Pack layer data into binary format for efficient transfer.

Returns (metadata, buffer) or None if this layer type does not support binary packing or use_binary is False. Subclasses override this to provide layer-specific packing.

as_widget

as_widget()

Wrap this layer in marimo.ui.anywidget for reactive .value access.

Equivalent to marimo.ui.anywidget(layer); provided so users do not need to import marimo themselves. The layer is wrapped via its backing Map (see :meth:_get_map), so the resulting widget exposes the same viewport / pick / hover state as a standalone Map.

__getattr__

__getattr__(name)

Proxy anywidget protocol attributes to the backing Map.

This allows mo.ui.anywidget(layer) to work transparently by delegating widget attributes (comm, _esm, _css, traits, etc.) to a lazily-created Map instance.

Core

deckgl_marimo.ScatterplotLayer

Bases: BinaryAttributesMixin, BaseLayer

Render circles at given positions.

Parameters:

Name	Type	Description	Default
data	Any	Input data (DataFrame, list of dicts, etc.)	None
get_position	PositionAccessor | None	Accessor for position. Column name(s) like ["lon", "lat"].	None
get_fill_color	ColorAccessor	Fill color accessor. Column name or constant like [255, 0, 0].	(0, 0, 0, 255)
get_line_color	ColorAccessor	Outline color accessor.	(0, 0, 0, 255)
get_radius	Accessor	Radius accessor. Column name or constant in meters.	1
radius_scale	float	Global radius multiplier.	1
radius_min_pixels	float	Minimum circle radius in pixels.	0
radius_max_pixels	float	Maximum circle radius in pixels.	MAX_SAFE_INTEGER
line_width_min_pixels	float	Minimum outline width in pixels.	0
stroked	bool	Whether to draw outlines.	False
filled	bool	Whether to fill circles.	True
billboard	bool	Whether circles always face the camera.	False

deckgl_marimo.GeoJsonLayer

Bases: BaseLayer

Render GeoJSON data (points, lines, polygons).

For authenticated remote data, use fetch_headers or load_options::

GeoJsonLayer(
    data="https://secure-api.example.com/data.geojson",
    fetch_headers={"Authorization": "Bearer my-token"},
)

Parameters:

Name	Type	Description	Default
data	Any	GeoJSON dict, GeoDataFrame, URL, or file path.	None
get_fill_color	ColorAccessor	Fill color for polygons/points.	(0, 0, 0, 255)
get_line_color	ColorAccessor	Stroke color for lines/polygon outlines.	(0, 0, 0, 255)
get_line_width	Accessor	Line width accessor.	1
get_point_radius	Accessor	Radius for point features.	1
filled	bool	Whether to fill polygons.	True
stroked	bool	Whether to stroke polygon outlines.	True
extruded	bool	Whether to extrude polygons in 3D.	False
point_type	str	How to render points: "circle", "icon", "text", or "circle+text".	'circle'
line_width_min_pixels	float	Minimum line width in pixels.	0

deckgl_marimo.ArcLayer

Bases: BinaryAttributesMixin, BaseLayer

Render arcs between source and target positions.

Parameters:

Name	Type	Description	Default
data	Any	Input data with source/target coordinates.	None
get_source_position	PositionAccessor | None	Source position accessor, e.g. ["src_lon", "src_lat"].	None
get_target_position	PositionAccessor | None	Target position accessor, e.g. ["dst_lon", "dst_lat"].	None
get_source_color	ColorAccessor	Source arc color.	(0, 0, 255, 255)
get_target_color	ColorAccessor	Target arc color.	(0, 200, 0, 255)
get_width	Accessor	Arc width accessor.	1
great_circle	bool	Whether to draw great circle arcs.	False

deckgl_marimo.PathLayer

Bases: BaseLayer

Render polyline paths.

Parameters:

Name	Type	Description	Default
data	Any	Input data containing path coordinates.	None
get_path	PositionAccessor | None	Path accessor. Column name containing coordinate arrays.	None
get_color	ColorAccessor	Path color accessor.	(0, 0, 0, 255)
get_width	Accessor	Path width accessor.	1
width_scale	float	Global width multiplier.	1
width_min_pixels	float	Minimum width in pixels.	0
rounded	bool	Whether to use rounded joints and caps.	False
billboard	bool	Whether paths always face the camera.	False

deckgl_marimo.PolygonLayer

Bases: BaseLayer

Render filled and/or stroked polygons.

Parameters:

Name	Type	Description	Default
data	Any	Input data containing polygon coordinates.	None
get_polygon	PositionAccessor | None	Polygon accessor. Column name containing coordinate arrays.	None
get_fill_color	ColorAccessor	Fill color accessor.	(0, 0, 0, 255)
get_line_color	ColorAccessor	Outline color accessor.	(0, 0, 0, 255)
get_line_width	Accessor	Outline width accessor.	1
filled	bool	Whether to fill polygons.	True
stroked	bool	Whether to draw outlines.	True
extruded	bool	Whether to extrude in 3D.	False
get_elevation	Accessor	Elevation accessor for 3D extrusion.	1000
elevation_scale	float	Global elevation multiplier.	1
line_width_units	str	Units for line width: "meters" (default), "common", or "pixels".	'meters'
line_width_scale	float	Global line width multiplier.	1
line_width_min_pixels	float	Minimum line width in pixels.	0
line_width_max_pixels	float	Maximum line width in pixels.	MAX_SAFE_INTEGER
wireframe	bool	Whether to draw the wireframe of extruded polygons.	False

Notes

With use_binary=True, the emitted layer spec switches to deck.gl's SolidPolygonLayer because the composite PolygonLayer does not support binary attributes. Stroke (stroked, get_line_color, get_line_width) is not rendered in binary mode.

deckgl_marimo.SolidPolygonLayer

Bases: BaseLayer

Render solid polygons (no stroke, better performance than PolygonLayer).

deckgl_marimo.LineLayer

Bases: BinaryAttributesMixin, BaseLayer

Render straight lines between pairs of points.

deckgl_marimo.PointCloudLayer

Bases: BinaryAttributesMixin, BaseLayer

Render a point cloud.

deckgl_marimo.IconLayer

Bases: BaseLayer

Render icons at given positions.

Parameters:

Name	Type	Description	Default
data	Any	Input data with position and icon info.	None
get_position	PositionAccessor | None	Position accessor.	None
get_icon	Accessor | None	Icon accessor. Returns icon name or object.	None
get_size	Accessor	Icon size accessor.	1
get_color	ColorAccessor	Icon tint color accessor.	(0, 0, 0, 255)
get_angle	Accessor	Icon rotation angle accessor.	0
icon_atlas	str | None	URL or image of the icon atlas spritesheet.	None
icon_mapping	dict | None	Dict mapping icon names to atlas regions.	None
size_scale	float	Global size multiplier.	1
billboard	bool	Whether icons always face the camera.	True

deckgl_marimo.TextLayer

Bases: BaseLayer

Render text labels at given positions.

Parameters:

Name	Type	Description	Default
data	Any	Input data with position and text info.	None
get_position	PositionAccessor | None	Position accessor.	None
get_text	Accessor | None	Text content accessor. Column name containing strings.	None
get_size	Accessor	Font size accessor.	32
get_color	ColorAccessor	Text color accessor.	(0, 0, 0, 255)
get_angle	Accessor	Text rotation angle accessor.	0
get_alignment_baseline	str	Vertical alignment: "top", "center", "bottom".	'center'
get_text_anchor	str	Horizontal alignment: "start", "middle", "end".	'middle'
font_family	str	CSS font family.	'Monaco, monospace'
size_scale	float	Global size multiplier.	1
billboard	bool	Whether text always faces the camera.	True

deckgl_marimo.ColumnLayer

Bases: BinaryAttributesMixin, BaseLayer

Render 3D columns (cylinders/prisms) at given positions.

Parameters:

Name	Type	Description	Default
data	Any	Input data with position info.	None
get_position	PositionAccessor | None	Position accessor.	None
get_fill_color	ColorAccessor	Column fill color accessor.	(255, 0, 0, 255)
get_line_color	ColorAccessor	Column outline color accessor.	(0, 0, 0, 255)
get_elevation	Accessor	Column height accessor.	1000
disk_resolution	int	Number of sides for the column polygon (higher = more circular).	20
radius	float	Column radius in meters.	1000
elevation_scale	float	Global elevation multiplier.	1
extruded	bool	Whether to extrude (must be True for 3D).	True

Aggregation

deckgl_marimo.HexagonLayer

Bases: BaseLayer

Aggregate data into hexagonal bins.

Parameters:

Name	Type	Description	Default
data	Any	Input data with position coordinates.	None
get_position	PositionAccessor | None	Position accessor, e.g. ["lon", "lat"].	None
radius	int	Hexagon bin radius in meters.	1000
elevation_scale	int	Height multiplier for extruded hexagons.	1
color_range	list | None	6-step color ramp as list of [r, g, b] lists.	None
extruded	bool	Whether to render hexagons as 3D columns.	False
coverage	float	Hexagon coverage ratio (0-1).	1.0
upper_percentile	int	Upper data percentile for color mapping (0-100).	100
gpu_aggregation	bool	Whether to perform aggregation on the GPU. Default True.	True

deckgl_marimo.HeatmapLayer

Bases: BaseLayer

Render a density heatmap.

Parameters:

Name	Type	Description	Default
data	Any	Input data with position coordinates.	None
get_position	PositionAccessor | None	Position accessor.	None
get_weight	Accessor	Weight accessor. Column name or constant.	1
radius_pixels	int	Heatmap kernel radius in pixels.	30
intensity	float	Heatmap intensity multiplier.	1
threshold	float	Minimum value threshold (0-1).	0.05
color_range	list | None	Color ramp for the heatmap.	None

Composite

deckgl_marimo.DisplacementLayer

Bases: BaseLayer

Visualize displacement between origin and reported/displaced positions.

Renders arcs between origin and displaced positions, with optional scatter dots at both endpoints. Useful for showing where something should be versus where it was reported.

Parameters:

Name	Type	Description	Default
data	Any	Input data (DataFrame, list of dicts, etc.) with columns for both origin and displaced positions.	None
origin	list[str] | None	Column names for the origin position, e.g. ["lon", "lat"].	None
displaced	list[str] | None	Column names for the displaced position, e.g. ["rep_lon", "rep_lat"].	None
show_arcs	bool	Whether to draw arcs between origin and displaced positions.	True
show_origin_dots	bool	Whether to draw dots at origin positions.	True
show_displaced_dots	bool	Whether to draw dots at displaced positions.	True
arc_width	Accessor	Arc width accessor or constant.	1
arc_source_color	ColorAccessor	Color at the origin end of the arc (default green).	(76, 175, 80, 200)
arc_target_color	ColorAccessor	Color at the displaced end of the arc (default red).	(244, 67, 54, 200)
great_circle	bool	Whether to draw great circle arcs.	False
origin_color	ColorAccessor	Fill color for origin dots (default green).	(76, 175, 80, 180)
origin_radius	Accessor	Radius for origin dots.	4
origin_radius_min_pixels	float	Minimum pixel radius for origin dots.	3
displaced_color	ColorAccessor	Fill color for displaced dots (default red).	(244, 67, 54, 180)
displaced_radius	Accessor	Radius for displaced dots.	4
displaced_radius_min_pixels	float	Minimum pixel radius for displaced dots.	3

deckgl_marimo.EllipseLayer

Bases: BaseLayer

Render ellipses or circles from center coordinates and axis dimensions.

Each row in the data produces an ellipse (or circle) polygon plus an optional center-point dot. Axis lengths can be given as diameters (default) or radii (is_semi=True), in meters, kilometers, or nautical miles.

Parameters:

Name	Type	Description	Default
data	Any	Input data (DataFrame, list of dicts, etc.) with columns for center coordinates and axis dimensions.	None
center	list[str] | None	Column names for the center position, e.g. ["lon", "lat"].	None
major_axis	str | float | None	Column name or constant value for the major axis length.	None
minor_axis	str | float | None	Column name or constant for the minor axis length. If None, defaults to major_axis (circle).	None
orientation	str | float	Column name or constant for the rotation angle. 0 = major axis points north, values increase clockwise.	0.0
is_semi	bool	If True axis values are radii; if False (default) they are diameters.	False
orientation_units	str	"degrees" (default) or "radians".	'degrees'
units	str	Length unit for axis values: "meters" (default), "kilometers", or "nautical_miles".	'meters'
num_vertices	int	Number of vertices for the polygon approximation.	64
show_center_dots	bool	Whether to render dots at ellipse centers.	False
fill_color	ColorAccessor	Fill color for the ellipse polygons.	(0, 140, 255, 100)
line_color	ColorAccessor	Outline color for the ellipse polygons.	(0, 100, 200, 255)
line_width	Accessor	Outline width for the ellipse polygons.	1
filled	bool	Whether to fill the ellipse polygons.	True
stroked	bool	Whether to stroke the ellipse outlines.	True
center_dot_color	ColorAccessor	Fill color for center dots.	(255, 255, 255, 255)
center_dot_radius	Accessor	Radius accessor or constant for center dots.	100
center_dot_radius_min_pixels	float	Minimum pixel radius for center dots.	4