geeViz.outputLib.thumbs¶

Generate Earth Engine thumbnails with automatic visualization handling.

geeViz.outputLib.thumbs provides functions that mirror the auto-visualization logic in geeView and geeViz.outputLib.charts — detecting thematic vs. continuous data, reading *_class_values / *_class_palette image properties, and building appropriate viz params — so you can get publication-ready thumbnail URLs and embeddable HTML <img> tags without manual configuration.

Supports ee.Image (PNG) and ee.ImageCollection (animated GIF or filmstrip), with optional per-feature clipping for ee.FeatureCollection geometries.

Animated GIFs¶

For ee.ImageCollection inputs, generate_gif() creates properly mosaicked per-time-step frames, with optional date burn-in using system:time_start metadata.

Example:

import geeViz.geeView as gv
from geeViz.outputLib import thumbs as tl

ee = gv.ee
lcms = ee.ImageCollection("USFS/GTAC/LCMS/v2024-10")
area = ee.Geometry.Point([-111.8, 40.7]).buffer(10000)

url = tl.get_thumb_url(lcms.select(["Land_Cover"]).first(), area)
html = tl.embed_thumb(url, title="LCMS Land Cover")

# Animated GIF with date labels
gif_html = tl.generate_gif(
    lcms.select(["Land_Cover"]),
    area,
    burn_in_date=True,
    date_format="YYYY",
)

Functions

`auto_viz`(ee_obj[, band_name, geometry, ...])	Build visualization parameters automatically from image properties.
`auto_viz_continuous`(image, geometry[, ...])	Build visualization parameters for a continuous `ee.Image` by sampling the region.
`download_thumb`(url[, timeout])	Download raw image bytes from an Earth Engine thumbnail URL.
`embed_thumb`(url[, title, width, download])	Generate an embeddable HTML `<figure>` element for a thumbnail.
`embed_thumb_grid`(thumb_results[, columns, ...])	Generate an HTML CSS-grid layout of multiple thumbnails.
`generate_filmstrip`(ee_obj, geometry[, ...])	Generate a filmstrip grid image from an Earth Engine ImageCollection.
`generate_gif`(ee_obj, geometry[, viz_params, ...])	Generate an animated GIF from an Earth Engine ImageCollection.
`generate_map_chart`(ee_obj, geometry[, ...])	Generate a combined map + chart output.
`generate_map_chart_gif`(ee_obj, geometry[, ...])	Generate an animated GIF with map thumbnails and cumulative line charts.
`generate_thumbs`(ee_obj, geometry[, ...])	Generate a publication-ready thumbnail PNG for a report section.
`get_animation_url`(ee_obj[, geometry, ...])	Get an animated GIF thumbnail URL for an `ee.ImageCollection`.
`get_filmstrip_url`(ee_obj[, geometry, ...])	Get a filmstrip thumbnail URL — all frames side-by-side in one PNG.
`get_thumb_url`(ee_obj[, geometry, ...])	Get a PNG thumbnail URL for an Earth Engine image.
`get_thumb_urls_by_feature`(ee_obj, features)	Get thumbnail URLs for an image clipped to each feature in a collection.
`get_thumb_urls_by_feature_parallel`(ee_obj, ...)	Generate per-feature thumbnail URLs in parallel using a thread pool.
`thumb_to_base64`(url[, timeout])	Download a thumbnail and return it as a base64 data URI string.

geeViz.outputLib.thumbs.auto_viz_continuous(image, geometry, band_names=None, stretch_type='percentile', percentiles=None, n_stddev=2, gamma=1.6, scale=600, timeout=10, max_scale=None)[source]¶

Build visualization parameters for a continuous ee.Image by sampling the region.

Performs a reduceRegion at a coarse resolution to compute stretch statistics. If the call times out the scale is doubled and retried until it succeeds or max_scale is exceeded.

Parameters:

image (ee.Image) – Image to visualize. Must not be an ee.ImageCollection — reduce the collection first.
geometry – ee.Geometry, ee.Feature, or ee.FeatureCollection defining the region to sample.
band_names (list or str, optional) – Bands to visualize — length must be 1 or 3. When None the first 3 bands are used (or first 1 if fewer than 3 exist). Defaults to None.
stretch_type (str) – One of "percentile" (default), "min-max", or "stddev".
percentiles (list[int], optional) – [lower, upper] percentiles for the "percentile" stretch. Defaults to [0, 95].
n_stddev (float) – Number of standard deviations for the "stddev" stretch (symmetric around the mean). Default 2.
gamma (float, optional) – Gamma correction applied to the output viz params. Values > 1 brighten midtones (lifts dark pixels without blowing out highlights); values < 1 darken midtones. 1.0 means no correction. Included in the returned dict as "gamma" when not 1.0. Defaults to 1.6.
scale (int) – Starting spatial resolution in meters for reduceRegion. Default 300.
timeout (int) – getInfo timeout in seconds per attempt. Default 5.
max_scale (int, optional) – Stop retrying when scale exceeds this value. Default is scale * 16 (4 doublings).

Returns:

Visualization parameters with bands, min, max keys, and gamma when gamma is not 1.0. min / max are scalars for single-band images and lists for 3-band images.

Return type:

dict

Raises:

TypeError – If image is an ee.ImageCollection.
ValueError – If band_names length is not 1 or 3, or if stretch_type is unrecognised.

Example

>>> viz = auto_viz_continuous(
...     s2_composite, study_area,
...     band_names=["swir2", "nir", "red"],
...     stretch_type="percentile", percentiles=[0, 99],
... )
>>> sorted(viz.keys())
['bands', 'gamma', 'max', 'min']
>>> viz["gamma"]
1.6

geeViz.outputLib.thumbs.auto_viz(ee_obj, band_name=None, geometry=None, stretch_type='percentile', percentiles=None, n_stddev=2, gamma=1.6, scale=600, timeout=10)[source]¶

Build visualization parameters automatically from image properties.

For thematic data (images with {band}_class_values and {band}_class_palette properties) returns a palette-based viz dict mapping class values to colors.

For continuous data:

When geometry is provided, delegates to auto_viz_continuous() which samples the region to compute data-driven min/max.
Otherwise falls back to hard-coded defaults.

Parameters:

ee_obj (ee.Image or ee.ImageCollection) – Earth Engine object to inspect.
band_name (str, optional) – Specific band to visualize.
geometry – ee.Geometry, ee.Feature, or ee.FeatureCollection. When provided continuous data is stretched from actual region values.
stretch_type (str) – Stretch for continuous data — "percentile" (default), "min-max", or "stddev".
percentiles (list[int], optional) – [lower, upper] for percentile stretch. Default [5, 95].
n_stddev (float) – Standard deviations for "stddev" stretch.
gamma (float, optional) – Gamma correction for continuous data. Values > 1 brighten midtones; < 1 darken. Included in the returned dict as "gamma" when not 1.0. Ignored for thematic data. Defaults to 1.6.
scale (int) – Starting scale (m) for reduceRegion.
timeout (int) – Timeout (s) per reduceRegion attempt.

Returns:

Visualization parameters suitable for ee.Image.getThumbURL(). For continuous data includes bands, min, max, and gamma (when not 1.0). For thematic data includes bands, min, max, and palette.

Return type:

dict

Example

>>> viz = auto_viz(lcms.select(["Land_Cover"]))
>>> viz["bands"]
['Land_Cover']

>>> viz = auto_viz(s2_composite, geometry=study_area,
...                stretch_type="percentile", percentiles=[2, 98])
>>> viz["gamma"]
1.6

geeViz.outputLib.thumbs.get_thumb_url(ee_obj, geometry=None, viz_params=None, dimensions=640, band_name=None, crs='EPSG:3857', transform=None, scale=None, burn_in_geometry=False, geometry_outline_color=None, geometry_fill_color=None, geometry_outline_weight=2, clip_to_geometry=True)[source]¶

Get a PNG thumbnail URL for an Earth Engine image.

Generates an ee.Image.getThumbURL() call with automatic visualization detection when viz_params is not supplied. The image is optionally clipped to geometry and reprojected when crs is provided. For ee.ImageCollection inputs, the collection is reduced to a single image (mode for thematic data, median for continuous).

Parameters:

ee_obj (ee.Image or ee.ImageCollection) – Image to thumbnail. Collections are reduced to a single representative image.
geometry (ee.Geometry or ee.Feature or ee.FeatureCollection, optional) – Region to clip and bound the thumbnail. Defaults to None (full image extent).
viz_params (dict, optional) – Visualization parameters (bands, min, max, palette, etc.). Auto-detected via auto_viz() when None. Defaults to None.
dimensions (int, optional) – Thumbnail width in pixels. Defaults to 640.
band_name (str, optional) – Band to visualize when using auto-detection. Defaults to None (first band).
crs (str, optional) – Output raster CRS. Passed directly to ee.Image.getThumbURL(crs=...) so EE renders the thumbnail in this projection. Defaults to "EPSG:3857" (Web Mercator). Pass None to omit the crs key entirely; EE then uses the source image’s native projection. (EE rejects a literal crs: null.)
transform (list, optional) – Affine transform as a 6-element list. Requires crs. Defaults to None.
scale (float, optional) – Nominal pixel scale in meters. Requires crs. Defaults to None.

Returns:

PNG thumbnail URL string from the Earth Engine servers.

Return type:

str

Raises:

ValueError – If transform or scale is provided without crs.

Example

>>> url = get_thumb_url(
...     image, study_area,
...     {"min": 0, "max": 3000, "bands": ["swir1", "nir", "red"]},
... )
>>> url[:5]
'https'

geeViz.outputLib.thumbs.get_animation_url(ee_obj, geometry=None, viz_params=None, dimensions=640, fps=1.5, band_name=None, max_frames=50, crs='EPSG:3857', transform=None, scale=None)[source]¶

Get an animated GIF thumbnail URL for an ee.ImageCollection.

Note

For tiled collections (LCMS, NLCD, etc.) this may produce blank frames. Use generate_gif() instead, which properly mosaics per time step and supports date burn-in.

Parameters:

ee_obj – ee.ImageCollection.
geometry – ee.Geometry, ee.Feature, or ee.FeatureCollection.
viz_params (dict, optional) – Must include bands (3 for RGB, or 1 + palette). Auto-detected if not provided.
dimensions (int) – Width in pixels.
fps (int) – Frames per second. Default 2.
band_name (str, optional) – Band to visualize (for auto_viz).
max_frames (int) – Maximum frames to include. Default 40.
crs (str, optional) – CRS code (e.g. "EPSG:4326").
transform (list, optional) – Affine transform. Requires crs.
scale (float, optional) – Nominal scale in meters. Requires crs.

Returns:

Animated GIF thumbnail URL.

Return type:

str

Raises:

ValueError – If transform or scale is provided without crs.

geeViz.outputLib.thumbs.get_filmstrip_url(ee_obj, geometry=None, viz_params=None, dimensions=640, band_name=None, max_frames=50, crs='EPSG:3857', transform=None, scale=None)[source]¶

Get a filmstrip thumbnail URL — all frames side-by-side in one PNG.

Parameters:

ee_obj – ee.ImageCollection.
geometry – Clip region.
viz_params (dict, optional) – Auto-detected if not provided.
dimensions (int) – Width per frame.
band_name (str, optional) – Band to visualize.
max_frames (int) – Maximum frames.
crs (str, optional) – CRS code (e.g. "EPSG:4326").
transform (list, optional) – Affine transform. Requires crs.
scale (float, optional) – Nominal scale in meters. Requires crs.

Returns:

Filmstrip PNG thumbnail URL.

Return type:

str

Raises:

ValueError – If transform or scale is provided without crs.

geeViz.outputLib.thumbs.generate_gif(ee_obj, geometry, viz_params=None, band_name=None, dimensions=640, fps=1.5, max_frames=50, burn_in_date=True, date_format=None, date_position='upper-left', date_font_size=None, burn_in_legend=True, legend_scale=1.0, bg_color=None, font_color=None, font_outline_color=None, output_path=None, crs='EPSG:3857', transform=None, scale=None, margin=16, basemap=None, overlay_opacity=None, scalebar=True, scalebar_units='metric', north_arrow=True, north_arrow_style='solid', inset_map=True, inset_basemap=None, inset_scale=0.3, inset_on_map=False, title=None, title_font_size=16, label_font_size=12, burn_in_geometry=False, geometry_outline_color=None, geometry_fill_color=None, geometry_outline_weight=2, clip_to_geometry=True, max_class_label_length=30)[source]¶

Generate an animated GIF from an Earth Engine ImageCollection.

Downloads individual frame thumbnails, properly mosaics tiled collections (LCMS, NLCD, etc.) by time step, and composites them into an animated GIF. Optional cartographic elements include date burn-in, thematic legend panel, basemap underlay, scalebar, north arrow, inset overview map, and title strip.

Parameters:

ee_obj (ee.ImageCollection) – Image collection to animate.
geometry (ee.Geometry or ee.Feature or ee.FeatureCollection) – Region to clip and bound each frame.
viz_params (dict, optional) – Visualization parameters (bands, min, max, palette). Auto-detected via auto_viz() when None. Defaults to None.
band_name (str, optional) – Band to visualize when using auto-detection. Defaults to None (first band).
dimensions (int, optional) – Width of each frame in pixels. Defaults to 640.
fps (int, optional) – Frames per second in the output GIF. Defaults to 2.
max_frames (int, optional) – Maximum number of frames to include. Defaults to 50.
burn_in_date (bool, optional) – Burn the date label from system:time_start into each frame. Defaults to True.
date_format (str, optional) – Date format string. Supported values include "YYYY", "YYYY-MM", "YYYY-MM-dd", "MMM YYYY", "MMMM YYYY", "MM/YYYY", "MM/dd/YYYY". Defaults to None — auto-detect from the collection’s temporal span (yearly for spans > 5y, monthly for shorter spans, daily for spans under 60 days, hourly for closely-spaced frames).
date_position (str, optional) – Position of the date label on each frame – "upper-left", "upper-right", "lower-left", or "lower-right". Defaults to "upper-left".
date_font_size (int, optional) – Font size in pixels for the date label. Default None (auto: 1.4× label_font_size).
burn_in_legend (bool, optional) – Append a legend panel to the right side of each frame for thematic data. Only rendered when class names and palette are available in image properties. Defaults to True.
legend_scale (float, optional) – Scale multiplier for the legend panel size. Defaults to 1.0.
bg_color (str or None, optional) – Background color for transparent areas, legend panel, and margins. Accepts CSS color names or hex strings. Resolved via theme when None. Defaults to None.
font_color (str or tuple or None, optional) – Text color for date labels and legend text. Resolved via theme when None. Defaults to None.
font_outline_color (str or tuple or None, optional) – Outline / halo color for text readability. Auto-derived to contrast with font_color when None. Defaults to None.
output_path (str, optional) – File path to save the GIF to disk. Parent directories are created automatically. Defaults to None (not saved).
crs (str, optional) – Output raster CRS for the rendered frames. Passed to ee.Image.getThumbURL(crs=...). Defaults to "EPSG:3857" (Web Mercator). Pass None to omit the crs key entirely; EE then uses the source image’s native projection. (EE rejects a literal crs: null.)
transform (list, optional) – Affine transform as a 6-element list. Requires crs. Defaults to None.
scale (float, optional) – Nominal pixel scale in meters. Requires crs. Defaults to None.
margin (int, optional) – Pixel margin on all sides of each frame. Defaults to 16.
basemap (str or dict or None, optional) – Basemap to composite behind the EE data. A preset name (e.g. "esri-satellite", "usfs-topo"), a config dict with type and url keys, or a raw tile URL template. Defaults to None (no basemap).
overlay_opacity (float or None, optional) – Opacity of the EE overlay when a basemap is present (0.0 – 1.0). Defaults to None (auto: 0.8 with basemap, 1.0 without).
scalebar (bool, optional) – Draw a scalebar on each frame. Only rendered when basemap or inset_basemap is set and bounds are available. Defaults to True.
scalebar_units (str, optional) – Unit system for the scalebar – "metric" or "imperial". Defaults to "metric".
north_arrow (bool, optional) – Draw a north arrow on each frame. Defaults to True.
north_arrow_style (str, optional) – Arrow style – "solid", "classic", or "outline". Defaults to "solid".
inset_map (bool, optional) – Include an inset overview map. Defaults to True.
inset_basemap (str or dict or None, optional) – Basemap for the inset. Falls back to basemap when None. Defaults to None.
inset_scale (float, optional) – Relative height of the inset compared to the frame height. Defaults to 0.3.
inset_on_map (bool, optional) – Place the inset directly on the main map frame (overlaid in the lower-right). Defaults to False — the inset is placed below the legend (or below the main frame if no legend exists). Set to True for a compact layout.
title (str, optional) – Title text rendered as a strip above the GIF frames. Defaults to None (no title).
title_font_size (int, optional) – Font size in pixels for the title strip. Defaults to 16.
label_font_size (int, optional) – Font size in pixels for legend labels and scalebar ticks. Defaults to 12.
burn_in_geometry (bool, optional) – Draw the study area geometry outline on each frame. Defaults to False.
geometry_outline_color (tuple or None, optional) – Color for the geometry outline. When None, auto-derived from font_color. Defaults to None.
geometry_fill_color (str or None, optional) – Fill color for the geometry interior. Defaults to None (no fill).
geometry_outline_weight (int, optional) – Line width in pixels for the geometry outline. Defaults to 2.
clip_to_geometry (bool, optional) – Clip imagery to the geometry boundary. Defaults to True.

Returns:

A dictionary with the following keys:

"html" (str): HTML <figure> element containing the GIF as a base64-embedded <img> tag.
"bytes" (bytes): Raw animated GIF byte data.
"format" (str): "gif".

Return type:

dict

Raises:

ValueError – If transform or scale is provided without crs.

Example

>>> result = generate_gif(
...     lcms.select(["Land_Cover"]),
...     study_area,
...     burn_in_date=True,
...     date_format="YYYY",
...     basemap="esri-satellite",
...     title="LCMS Land Cover",
... )
>>> gif_bytes = result["bytes"]
>>> html_snippet = result["html"]

geeViz.outputLib.thumbs.generate_filmstrip(ee_obj, geometry, viz_params=None, band_name=None, dimensions=640, max_frames=50, columns=3, date_format=None, burn_in_legend=True, legend_scale=1.0, legend_position='bottom', bg_color=None, font_color=None, font_outline_color=None, output_path=None, crs='EPSG:3857', transform=None, scale=None, margin=16, basemap=None, overlay_opacity=None, scalebar=True, scalebar_units='metric', north_arrow=True, north_arrow_style='solid', inset_map=True, inset_basemap=None, inset_scale=0.3, inset_on_map=False, title=None, burn_in_geometry=False, geometry_outline_color=None, geometry_fill_color=None, geometry_outline_weight=2, clip_to_geometry=True, geometry_legend_label='Study Area', title_font_size=16, label_font_size=12, max_class_label_length=30)[source]¶

Generate a filmstrip grid image from an Earth Engine ImageCollection.

Downloads individual frame thumbnails, mosaics tiled collections by date, labels each frame with its date, and arranges them in a grid layout. Optionally composites a basemap behind the EE data and appends cartographic elements including a legend panel, scalebar, north arrow, inset overview map, and title strip.

Parameters:

ee_obj (ee.ImageCollection) – Image collection to render.
geometry (ee.Geometry or ee.Feature or ee.FeatureCollection) – Region to clip and bound each frame.
viz_params (dict, optional) – Visualization parameters (bands, min, max, palette). Auto-detected via auto_viz() when None. Defaults to None.
band_name (str, optional) – Band to visualize when using auto-detection. Defaults to None (first band).
dimensions (int, optional) – Width per frame in pixels. Defaults to 640.
max_frames (int, optional) – Maximum number of frames to include in the grid. Defaults to 50.
columns (int, optional) – Number of columns in the grid layout. Defaults to 3.
date_format (str, optional) – Date label format above each frame. Supports "YYYY", "YYYY-MM", "YYYY-MM-dd", "MMM YYYY", etc. Defaults to None — auto-detect from the collection’s temporal span.
burn_in_legend (bool, optional) – Append a legend panel for thematic data. Only rendered when class names and palette are available. Defaults to True.
legend_scale (float, optional) – Scale multiplier for legend size. Defaults to 1.0.
legend_position (str, optional) – Where to place the legend relative to the grid – "bottom" or "top". Defaults to "bottom".
bg_color (str or None, optional) – Background color for the grid, margins, and legend panel. Resolved via theme when None. Defaults to None.
font_color (str or tuple or None, optional) – Text color for date labels and legend text. Resolved via theme when None. Defaults to None.
font_outline_color (str or tuple or None, optional) – Outline / halo color for text readability. Auto-derived when None. Defaults to None.
output_path (str, optional) – File path to save the PNG. Parent directories are created automatically. Defaults to None (not saved).
crs (str, optional) – Output raster CRS for the rendered frames. Passed to ee.Image.getThumbURL(crs=...). Defaults to "EPSG:3857" (Web Mercator). Pass None to omit the crs key entirely; EE then uses the source image’s native projection. (EE rejects a literal crs: null.)
transform (list, optional) – Affine transform as a 6-element list. Requires crs. Defaults to None.
scale (float, optional) – Nominal pixel scale in meters. Requires crs. Defaults to None.
margin (int, optional) – Pixel margin on all sides of the final image. Defaults to 16.
basemap (str or dict or None, optional) – Basemap to composite behind each frame. A preset name (e.g. "esri-satellite"), a config dict, or a raw tile URL. Defaults to None (no basemap).
overlay_opacity (float or None, optional) – Opacity of the EE overlay when a basemap is present (0.0 – 1.0). Defaults to None (auto: 0.8 with basemap, 1.0 without).
scalebar (bool, optional) – Include a scalebar below the grid. Only rendered when cartographic context is available. Defaults to True.
scalebar_units (str, optional) – Unit system for the scalebar – "metric" or "imperial". Defaults to "metric".
north_arrow (bool, optional) – Include a north arrow below the grid. Defaults to True.
north_arrow_style (str, optional) – Arrow style – "solid", "classic", or "outline". Defaults to "solid".
inset_map (bool, optional) – Include an inset overview map below the grid. Defaults to True.
inset_basemap (str or dict or None, optional) – Basemap for the inset. Falls back to basemap when None. Defaults to None.
inset_scale (float, optional) – Relative height of the inset compared to the frame height. Defaults to 0.3.
inset_on_map (bool, optional) – Place the inset on the map rather than as a separate strip. For filmstrips this controls positioning in the bottom strip area. Defaults to False.
title (str, optional) – Title text rendered as a strip above the grid. Defaults to None (no title).
title_font_size (int, optional) – Font size in pixels for the title strip. Defaults to 16.
label_font_size (int, optional) – Font size in pixels for legend labels and scalebar ticks. Defaults to 12.
burn_in_geometry (bool, optional) – Draw the study area geometry outline on each frame. Defaults to False.
geometry_outline_color (tuple or None, optional) – Color for the geometry outline. When None, auto-derived from font_color. Defaults to None.
geometry_fill_color (str or None, optional) – Fill color for the geometry interior. Defaults to None (no fill).
geometry_outline_weight (int, optional) – Line width in pixels for the geometry outline. Defaults to 2.
clip_to_geometry (bool, optional) – Clip imagery to the geometry boundary. Defaults to True.
geometry_legend_label (str, optional) – Label for the geometry in the legend. Defaults to "Study Area".

Returns:

A dictionary with the following keys:

"html" (str): HTML <figure> element containing the filmstrip as a base64-embedded PNG <img> tag.
"bytes" (bytes): Raw PNG byte data.
"format" (str): "png".

Return type:

dict

Raises:

ValueError – If transform or scale is provided without crs.

Example

>>> result = generate_filmstrip(
...     lcms.select(["Land_Cover"]),
...     study_area,
...     columns=4,
...     date_format="YYYY",
...     basemap="esri-satellite",
...     title="LCMS Land Cover Time Series",
... )
>>> png_bytes = result["bytes"]

geeViz.outputLib.thumbs.generate_map_chart(ee_obj, geometry, viz_params=None, band_name=None, dimensions=640, bg_color=None, font_color=None, font_outline_color=None, output_path=None, crs='EPSG:3857', transform=None, scale=None, margin=16, basemap=None, overlay_opacity=None, scalebar=True, scalebar_units='metric', north_arrow=True, north_arrow_style='solid', inset_map=True, inset_basemap=None, inset_scale=0.25, title=None, chart_type=None, chart_scale=30, area_format='Percentage', chart_height=None, legend_position='right', include_masked_area=True, burn_in_geometry=True, burn_in_legend=True, title_font_size=16, label_font_size=12, geometry_outline_color=None, geometry_fill_color=None, geometry_outline_weight=2, clip_to_geometry=True, feature_label=None, columns=2, thumb_width=None, band_names=None, thematic_band_name=None, opacity=0.7, layout='side-by-side')[source]¶

Generate a combined map + chart output.

For ee.Image inputs, produces a static PNG with a map thumbnail beside (or above) a chart. For ee.ImageCollection inputs, automatically delegates to generate_map_chart_gif() and returns an animated GIF with cumulative time-series charts.

The title appears once on the combined output — the chart itself has no title. For thematic data the legend appears on the map thumbnail only (not duplicated on the chart).

Supports:

ee.Image + single geometry (ee.Geometry / ee.Feature) with thematic data -> map + bar or donut chart
ee.Image + single geometry with continuous data -> map + horizontal bar chart of band means
ee.Image + multi-feature ee.FeatureCollection with thematic data -> per-feature map grid + grouped/stacked bar or per-feature donut chart
ee.Image + multi-feature FC with chart_type="scatter" -> map of bounding region with sample points burned in + scatter plot (optionally colored by thematic_band_name)
ee.ImageCollection + any geometry -> delegates to generate_map_chart_gif(), returning bytes (GIF format)

Parameters:

ee_obj – ee.Image or ee.ImageCollection.
geometry – ee.Geometry, ee.Feature, or ee.FeatureCollection.
viz_params (dict, optional) – Visualization parameters for the map thumbnail. Auto-detected via auto_viz() when None.
band_name (str, optional) – Band to visualize on the map.
dimensions (int, optional) – Map thumbnail width in pixels. Defaults to 640.
bg_color (str, optional) – Background color. Dark theme when None.
font_color (str or tuple, optional) – Font color override.
font_outline_color (str or tuple, optional) – Font outline.
output_path (str, optional) – Save output to this path.
crs (str, optional) – Output raster CRS. Passed to ee.Image.getThumbURL(crs=...). Defaults to "EPSG:3857". Pass None to omit the crs key (EE then uses the image’s native projection; EE rejects a literal crs: null).
transform (list, optional) – CRS transform.
scale (int, optional) – Pixel scale in metres.
margin (int, optional) – Margin around the output in pixels.
basemap (str or dict, optional) – Basemap preset name (e.g. "esri-satellite") or config dict.
overlay_opacity (float, optional) – Opacity of EE data over basemap. Default 0.8 when basemap is set.
scalebar (bool, optional) – Draw scalebar. Defaults to True.
scalebar_units (str, optional) – "metric" or "imperial".
north_arrow (bool, optional) – Draw north arrow. Defaults to True.
north_arrow_style (str, optional) – Arrow style.
inset_map (bool, optional) – Show inset overview map.
inset_basemap – Basemap for inset.
inset_scale (float, optional) – Inset size as fraction of frame.
title (str, optional) – Title displayed once above the combined map + chart output.
chart_type (str, optional) – "bar" (default for Image), "stacked_bar", "donut", "scatter", or any time-series type ("line+markers", etc.). None auto-detects: "bar" for Image, "line+markers" for ImageCollection.
chart_scale (int, optional) – Scale in metres for zonal stats reduceRegion. Defaults to 30.
area_format (str, optional) – "Percentage" (default), "Hectares", "Acres", or "Pixels".
chart_height (int, optional) – Chart height in pixels. Defaults to map height for side-by-side, map width for stacked.
legend_position (str or dict, optional) – Chart legend position. Suppressed automatically for thematic data when burn_in_legend=True (legend on thumb only).
include_masked_area (bool, optional) – Include masked pixels in area totals. Defaults to True.
burn_in_geometry (bool, optional) – Paint geometry boundary on map frames. Defaults to True.
burn_in_legend (bool, optional) – Add legend panel to the map thumbnail. Defaults to True.
title_font_size (int, optional) – Title font size. Default 16.
label_font_size (int, optional) – Label font size. Default 12.
geometry_outline_color (str, optional) – Boundary color.
geometry_fill_color (str, optional) – Boundary fill (hex+alpha).
geometry_outline_weight (int, optional) – Boundary width.
clip_to_geometry (bool, optional) – Mask data outside boundary.
feature_label (str, optional) – FC property name for per-feature labels (multi-feature mode).
columns (int, optional) – Columns for multi-feature grid or multi-feature donut subplot layout. Defaults to 2.
thumb_width (int, optional) – Per-feature thumbnail width.
band_names (list[str], optional) – Bands for scatter x/y axes. Uses first two image bands when None.
thematic_band_name (str, optional) – Thematic band name for coloring scatter points by class. The image must carry {band}_class_values/names/palette properties.
opacity (float, optional) – Point opacity for scatter charts. Defaults to 0.7.
layout (str, optional) – "side-by-side" (default) places the chart to the right of the map. "stacked" places the chart below the map.

Returns:

For ee.Image inputs:: {"html": str, "bytes": bytes, "format": "png", "df": DataFrame, "fig": Figure}. For ee.ImageCollection inputs (delegated to GIF): {"html": str, "bytes": bytes, "format": "gif"}.

Return type:

dict

geeViz.outputLib.thumbs.generate_map_chart_gif(ee_obj, geometry, viz_params=None, band_name=None, dimensions=640, fps=1.5, max_frames=50, date_format=None, bg_color=None, font_color=None, font_outline_color=None, output_path=None, crs='EPSG:3857', transform=None, scale=None, margin=16, basemap=None, overlay_opacity=None, scalebar=True, scalebar_units='metric', north_arrow=True, north_arrow_style='solid', inset_map=True, inset_basemap=None, inset_scale=0.25, title=None, chart_type='line+markers', chart_scale=30, area_format='Percentage', chart_height=None, legend_position='bottom', include_masked_area=True, burn_in_geometry=True, title_font_size=16, label_font_size=12, geometry_outline_color=None, geometry_fill_color=None, geometry_outline_weight=2, clip_to_geometry=True, max_class_label_length=30)[source]¶

Generate an animated GIF with map thumbnails and cumulative line charts.

Each frame shows a map thumbnail for one time step above a chart that accumulates data from the first year up to the current year. The chart’s x-axis spans the full time range so the frame-to-frame progression is visually stable. A legend is placed below the chart.

Delegates map frame generation to generate_gif() (which handles basemap compositing, scalebar, north arrow, inset map, geometry burn-in, etc.) and runs cl.zonal_stats() in parallel. The GIF frames are then decomposed and composited with per-frame cumulative charts.

This mirrors the layout of https://storage.googleapis.com/lcms-gifs/San_Juan_NF_Land_Cover.gif.

Parameters:

ee_obj (ee.ImageCollection) – Multi-temporal image collection.
geometry – ee.Geometry, ee.Feature, or ee.FeatureCollection.
viz_params (dict, optional) – Viz params for the map thumbnails. Auto-detected when None.
band_name (str, optional) – Band to visualize.
dimensions (int) – Map thumbnail width in pixels.
fps (int) – Frames per second.
max_frames (int) – Max number of frames.
date_format (str, optional) – Date format for labels (e.g. "YYYY-MM"). Defaults to None — auto-detect from the collection’s temporal span.
bg_color – Background color.
font_color – Font color.
font_outline_color – Font outline color.
output_path (str, optional) – Save GIF to this path.
crs – Projection params for thumbnails.
transform – Projection params for thumbnails.
scale – Projection params for thumbnails.
margin (int) – Margin in pixels.
basemap – Basemap preset for map thumbnails.
overlay_opacity (float) – Opacity of EE data over basemap.
scalebar (bool) – Draw scalebar on map.
scalebar_units (str) – "metric" or "imperial".
north_arrow (bool) – Draw north arrow on map.
north_arrow_style (str) – Arrow style.
title (str, optional) – Title above the map.
chart_type (str) – Chart type for the time series. Default "line+markers".
chart_scale (int) – Scale in metres for reduceRegion.
area_format (str) – "Percentage", "Hectares", "Acres".
chart_height (int, optional) – Chart height in pixels. Default is dimensions * 0.6.
legend_position (str or dict) – Legend placement on chart.

Returns:

{"html": str, "bytes": bytes, "format": "gif"}

Return type:

dict

geeViz.outputLib.thumbs.get_thumb_urls_by_feature(ee_obj, features, viz_params=None, dimensions=640, feature_label=None, band_name=None, max_features=10)[source]¶

Get thumbnail URLs for an image clipped to each feature in a collection.

Iterates over features sequentially, clipping the image to each feature’s geometry and generating a separate thumbnail URL. For faster processing with many features, use get_thumb_urls_by_feature_parallel() instead.

Parameters:

ee_obj (ee.Image or ee.ImageCollection) – Image to thumbnail. Collections are reduced to a single representative image.
features (ee.FeatureCollection) – Collection of features; each feature’s geometry is used to clip a separate thumbnail.
viz_params (dict, optional) – Visualization parameters. Auto-detected via auto_viz() when None. Defaults to None.
dimensions (int, optional) – Width in pixels per thumbnail. Defaults to 640.
feature_label (str, optional) – Property name to use as a human-readable label for each feature. Auto-detected when None. Defaults to None.
band_name (str, optional) – Band to visualize when using auto-detection. Defaults to None.
max_features (int, optional) – Maximum number of features to process. Defaults to 10.

Returns:

List of dictionaries, one per feature, each containing:

"label" (str): Feature label from feature_label property.
"url" (str): PNG thumbnail URL.
"geometry" (ee.Geometry): The feature’s geometry.

Return type:

list[dict]

Example

>>> results = get_thumb_urls_by_feature(
...     image, counties.limit(3), feature_label="NAME",
... )
>>> results[0].keys()
dict_keys(['label', 'url', 'geometry'])

geeViz.outputLib.thumbs.get_thumb_urls_by_feature_parallel(ee_obj, features, viz_params=None, dimensions=640, feature_label=None, band_name=None, max_features=10, max_workers=6, burn_in_params=None, clip_to_geometry=True)[source]¶

Generate per-feature thumbnail URLs in parallel using a thread pool.

Like get_thumb_urls_by_feature(), but uses concurrent.futures.ThreadPoolExecutor to issue multiple getThumbURL() requests concurrently, significantly reducing wall-clock time for collections with many features.

Parameters:

ee_obj (ee.Image or ee.ImageCollection) – Image to thumbnail. Collections are reduced to a single representative image.
features (ee.FeatureCollection) – Collection of features; each feature’s geometry is used to clip a separate thumbnail.
viz_params (dict, optional) – Visualization parameters. Auto-detected via auto_viz() when None. Defaults to None.
dimensions (int, optional) – Width in pixels per thumbnail. Defaults to 640.
feature_label (str, optional) – Property name to use as a human-readable label for each feature. Auto-detected when None. Defaults to None.
band_name (str, optional) – Band to visualize when using auto-detection. Defaults to None.
max_features (int, optional) – Maximum number of features to process. Defaults to 10.
max_workers (int, optional) – Maximum threads in the pool. Defaults to 6.

Returns:

List of dictionaries, one per feature, each containing:

"label" (str): Feature label from feature_label property.
"url" (str): PNG thumbnail URL.

Return type:

list[dict]

Example

>>> counties = ee.FeatureCollection("TIGER/2018/Counties")
>>> results = get_thumb_urls_by_feature_parallel(
...     image, counties.limit(5),
...     feature_label="NAME",
... )
>>> results[0]["label"]
'Some County'

geeViz.outputLib.thumbs.download_thumb(url, timeout=120)[source]¶

Download raw image bytes from an Earth Engine thumbnail URL.

Fetches the PNG or GIF data from a URL returned by ee.Image.getThumbURL() or ee.ImageCollection.getVideoThumbURL().

Parameters:

url (str) – Thumbnail URL from getThumbURL() or getVideoThumbURL().
timeout (int, optional) – HTTP request timeout in seconds. Defaults to 120.

Returns:

Raw image data (PNG or GIF format).

Return type:

bytes

Example

>>> data = download_thumb("https://earthengine.googleapis.com/...")
>>> len(data) > 0
True

geeViz.outputLib.thumbs.thumb_to_base64(url, timeout=120)[source]¶

Download a thumbnail and return it as a base64 data URI string.

Fetches image bytes from the given URL, detects the format (PNG or GIF) from the magic bytes, and encodes the result as a data:image/...;base64,... URI suitable for embedding in HTML.

Parameters:

url (str) – Thumbnail URL from getThumbURL() or getVideoThumbURL().
timeout (int, optional) – HTTP request timeout in seconds. Defaults to 120.

Returns:

Base64 data URI string (e.g. "data:image/png;base64,iVBOR...").

Return type:

str

Example

>>> data_uri = thumb_to_base64("https://earthengine.googleapis.com/...")
>>> data_uri.startswith("data:image/")
True

geeViz.outputLib.thumbs.embed_thumb(url, title='', width=None, download=False)[source]¶

Generate an embeddable HTML <figure> element for a thumbnail.

Wraps a thumbnail URL (or base64 data URI) in an HTML <figure> with an <img> tag and optional <figcaption>. When download is True the image bytes are fetched and embedded inline as a base64 data URI so the resulting HTML is fully self-contained.

Parameters:

url (str) – Thumbnail URL from getThumbURL() or a data:image/... base64 data URI.
title (str, optional) – Alt text and caption for the image. Defaults to "".
width (int, optional) – CSS width in pixels applied via an inline style. Defaults to None (natural size).
download (bool, optional) – Download the image from url and embed it as a base64 data URI for self-contained HTML. Defaults to False (reference the URL directly).

Returns:

HTML string containing a <figure> with <img> and optional <figcaption> elements.

Return type:

str

Example

>>> html = embed_thumb(
...     "https://earthengine.googleapis.com/...",
...     title="Study Area", width=400,
... )
>>> "<img" in html
True

geeViz.outputLib.thumbs.embed_thumb_grid(thumb_results, columns=3, thumb_width=300, download=False)[source]¶

Generate an HTML CSS-grid layout of multiple thumbnails.

Takes a list of per-feature thumbnail results (from get_thumb_urls_by_feature() or get_thumb_urls_by_feature_parallel()) and assembles them into a responsive CSS grid <div> with labeled <figure> elements.

Parameters:

thumb_results (list[dict]) – List of thumbnail result dictionaries, each containing "label" (str) and "url" (str) keys.
columns (int, optional) – Number of grid columns. Defaults to 3.
thumb_width (int, optional) – Display width in pixels for each thumbnail image. Defaults to 300.
download (bool, optional) – Download each image and embed as base64 for self-contained HTML. Defaults to False.

Returns:

HTML string containing a <div> with CSS grid styling and one <figure> per thumbnail.

Return type:

str

Example

>>> results = get_thumb_urls_by_feature_parallel(image, counties)
>>> grid_html = embed_thumb_grid(results, columns=4, thumb_width=250)
>>> "thumb-grid" in grid_html
True

geeViz.outputLib.thumbs.generate_thumbs(ee_obj, geometry, viz_params=None, band_name=None, dimensions=640, feature_label=None, max_features=6, columns=3, thumb_width=300, burn_in_legend=True, legend_scale=1.0, bg_color=None, font_color=None, font_outline_color=None, output_path=None, crs='EPSG:3857', transform=None, scale=None, margin=16, basemap=None, overlay_opacity=None, scalebar=True, scalebar_units='metric', north_arrow=True, north_arrow_style='solid', inset_map=True, inset_basemap=None, inset_scale=0.3, inset_on_map=False, title=None, burn_in_geometry=False, geometry_outline_color=None, geometry_fill_color=None, geometry_outline_weight=2, clip_to_geometry=True, geometry_legend_label='Study Area', title_font_size=16, label_font_size=12, max_class_label_length=30)[source]¶

Generate a publication-ready thumbnail PNG for a report section.

Provides an all-in-one workflow: auto-viz detection, thumbnail URL generation, image download, basemap compositing, and optional cartographic embellishments (legend, scalebar, north arrow, inset map, title).

For ee.FeatureCollection geometries with multiple features, produces a labeled grid of per-feature thumbnails. For single geometries, produces a single thumbnail with optional cartographic elements.

For ee.ImageCollection input, the collection is reduced to a single representative image using the temporal mode (thematic data) or median (continuous data).

Parameters:

ee_obj (ee.Image or ee.ImageCollection) – Image to thumbnail. Collections are reduced to a single representative image.
geometry (ee.Geometry or ee.Feature or ee.FeatureCollection) – Region to clip and bound the thumbnail. When a FeatureCollection with multiple features is provided, a per-feature grid is generated instead.
viz_params (dict, optional) – Visualization parameters (bands, min, max, palette). Auto-detected via auto_viz() when None. Defaults to None.
band_name (str, optional) – Band to visualize when using auto-detection. Defaults to None (first band).
dimensions (int, optional) – Thumbnail width in pixels. Defaults to 640.
feature_label (str, optional) – Property name for per-feature labels in grid mode. Auto-detected when None. Defaults to None.
max_features (int, optional) – Maximum features to include in the grid. Defaults to 6.
columns (int, optional) – Number of columns in the per-feature grid. Defaults to 3.
thumb_width (int, optional) – Width in pixels for each cell in the per-feature grid. Defaults to 300.
burn_in_legend (bool, optional) – Append a legend panel for thematic data. Only rendered when class names and palette are available in image properties. Defaults to True.
legend_scale (float, optional) – Scale multiplier for the legend panel size. Defaults to 1.0.
bg_color (str or None, optional) – Background color for margins, legend panel, and transparent areas. Resolved via theme when None. Defaults to None.
font_color (str or tuple or None, optional) – Text color for labels and legend text. Resolved via theme when None. Defaults to None.
font_outline_color (str or tuple or None, optional) – Outline / halo color for text readability. Auto-derived when None. Defaults to None.
output_path (str, optional) – File path to save the PNG. Parent directories are created automatically. Defaults to None (not saved).
crs (str, optional) – Output raster CRS. Passed to ee.Image.getThumbURL(crs=...). Defaults to "EPSG:3857" (Web Mercator). Pass None to omit the crs key entirely; EE then uses the source image’s native projection. (EE rejects a literal crs: null.)
transform (list, optional) – Affine transform as a 6-element list. Requires crs. Defaults to None.
scale (float, optional) – Nominal pixel scale in meters. Requires crs. Defaults to None.
margin (int, optional) – Pixel margin on all sides of the final image. Defaults to 16.
basemap (str or dict or None, optional) – Basemap to composite behind the EE data. A preset name (e.g. "esri-satellite", "usfs-topo"), a config dict with type and url keys, or a raw tile URL template. Defaults to None (no basemap).
overlay_opacity (float or None, optional) – Opacity of the EE overlay when a basemap is present (0.0 – 1.0). Defaults to None (auto: 0.8 with basemap, 1.0 without).
scalebar (bool, optional) – Draw a scalebar on the thumbnail. Only rendered when cartographic context is available. Defaults to True.
scalebar_units (str, optional) – Unit system for the scalebar – "metric" or "imperial". Defaults to "metric".
north_arrow (bool, optional) – Draw a north arrow on the thumbnail. Defaults to True.
north_arrow_style (str, optional) – Arrow style – "solid", "classic", or "outline". Defaults to "solid".
inset_map (bool, optional) – Include an inset overview map. Defaults to True.
inset_basemap (str or dict or None, optional) – Basemap for the inset. Falls back to basemap when None. Defaults to None.
inset_scale (float, optional) – Relative height of the inset compared to the frame height. Defaults to 0.3.
inset_on_map (bool, optional) – Place the inset directly on the map rather than below it. Defaults to False.
title (str, optional) – Title text rendered as a strip above the thumbnail. Defaults to None (no title).
burn_in_geometry (bool, optional) – Paint the geometry boundary outline onto the image using FeatureCollection.style(). Defaults to False.
geometry_outline_color (tuple or None, optional) – (R, G, B) color for the boundary outline. When None, auto-detected from the basemap luminance. Defaults to None.
geometry_fill_color (str or None, optional) – CSS fill color for the geometry interior (e.g. "33333366"). Used for geometry-only thumbnails (ee_obj=None). Defaults to None.
geometry_outline_weight (int, optional) – Width of the boundary outline in pixels. Defaults to 2.
geometry_legend_label (str, optional) – Label for the geometry swatch in the legend. Defaults to "Study Area".
clip_to_geometry (bool, optional) – When True, clip the image to the geometry. When False, use the geometry’s bounding box as the region (data extends beyond boundary). Defaults to True.
title_font_size (int, optional) – Font size in pixels for the title strip. Defaults to 16.
label_font_size (int, optional) – Font size in pixels for date labels, feature labels, scalebar ticks, and legend text. Defaults to 12.

Returns:

A dictionary with the following keys:

"html" (str): HTML <figure> element containing the thumbnail as a base64-embedded <img> tag.
"bytes" (bytes): Raw PNG byte data.
"format" (str): "png".
"is_grid" (bool): True if a multi-feature grid was produced, False for a single thumbnail.

Return type:

dict

Raises:

ValueError – If transform or scale is provided without crs.

Example

>>> result = generate_thumbs(
...     lcms.select(["Land_Cover"]).first(),
...     study_area,
...     basemap="esri-satellite",
...     title="LCMS Land Cover 2023",
... )
>>> result["is_grid"]
False
>>> len(result["bytes"]) > 0
True