geeViz.googleMapsLib¶

Google Maps Platform client for geeViz.

Provides functions for ground-truthing and enriching remote sensing analysis using Google Maps Platform APIs:

Geocoding — address to coordinates and reverse
Places — search, nearby, details, photos
Street View — static images, panoramas, AI interpretation
Elevation — terrain height at any location
Static Maps — basemap images for reports
Air Quality — current AQI and pollutants
Solar — rooftop solar potential
Roads — snap GPS traces to nearest roads

24 public functions:

Geocoding: geocode, reverse_geocode, validate_address
Places: search_places, search_nearby, get_place_photo
Street View: streetview_metadata, streetview_image, streetview_images_cardinal, streetview_panorama, streetview_html
AI Analysis: interpret_image, label_streetview, segment_image, segment_streetview
Elevation: get_elevation, get_elevations, get_elevation_along_path
Environment: get_air_quality, get_solar_insights, get_timezone
Maps: get_static_map
Roads: snap_to_roads, nearest_roads

Quick start:

import geeViz.googleMapsLib as gm

# Geocode an address
result = gm.geocode("100 S 200 E, Salt Lake City, UT")

# Street View panorama + AI interpretation
pano = gm.streetview_panorama(-111.80, 40.68, fov=360)
analysis = gm.interpret_image(pano)

# Semantic segmentation (SegFormer)
seg = gm.segment_image(pano, model_variant="b4")

# Elevation, air quality, solar
elev = gm.get_elevation(-111.80, 40.68)
aq = gm.get_air_quality(-111.80, 40.68)
solar = gm.get_solar_insights(-111.80, 40.68)

Requires a GOOGLE_MAPS_PLATFORM_API_KEY in your environment or .env file. Gemini AI features use GEMINI_API_KEY.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Functions

`geocode`(address)	Geocode an address to coordinates using the Google Geocoding API.
`get_air_quality`(lon, lat)	Get current air quality conditions at a location.
`get_elevation`(lon, lat)	Get elevation in meters at a geographic location.
`get_elevation_along_path`(points[, samples])	Get elevation profile along a path.
`get_elevations`(points)	Get elevations for multiple locations in one request.
`get_place_photo`(photo_name[, max_width, ...])	Fetch a place photo by its resource name.
`get_solar_insights`(lon, lat[, quality])	Get rooftop solar potential for the nearest building.
`get_static_map`(lon, lat[, zoom, size, ...])	Get a static map image centered on a location.
`get_timezone`(lon, lat[, timestamp])	Get timezone information for a location.
`interpret_image`(image_bytes[, mode, prompt, ...])	Interpret a Street View or static-map image using Google Gemini.
`label_image`(image_bytes[, mode, prompt, ...])	Detect and label objects in an image using Gemini vision.
`label_streetview`(lon, lat[, prompt, ...])	Fetch a Street View panorama and label objects on it.
`nearest_roads`(lon, lat)	Find the nearest road segments to a point.
`reverse_geocode`(lon, lat)	Convert coordinates to an address (reverse geocoding).
`search_nearby`(lat, lon[, radius, ...])	Search for places near a location using Nearby Search (New).
`search_places`(query[, lat, lon, radius, ...])	Search for places using the Google Places API (New) Text Search.
`segment_image`(image_bytes[, mode, ...])	Perform pixel-level semantic segmentation on an RGB image.
`segment_streetview`(lon, lat[, heading, fov, ...])	Fetch a Street View panorama and segment it with SegFormer.
`snap_to_roads`(points[, interpolate])	Snap GPS points to the nearest road segments.
`streetview_html`(lon, lat[, headings, pitch, ...])	Generate an HTML panel with embedded Street View images.
`streetview_image`(lon, lat[, heading, pitch, ...])	Fetch a Street View static image as JPEG bytes.
`streetview_images_cardinal`(lon, lat[, ...])	Fetch Street View images looking N, E, S, and W.
`streetview_metadata`(lon, lat[, radius, source])	Check if Street View imagery exists at a location.
`streetview_panorama`(lon, lat[, heading, ...])	Fetch a wide-angle or full 360° Street View panorama as a stitched image.
`validate_address`(address[, region_code])	Validate and standardize an address.

geeViz.googleMapsLib.geocode(address: str) → dict[str, Any] | None[source]¶

Geocode an address to coordinates using the Google Geocoding API.

Parameters:

address (str) – Street address, place name, or location description.

Returns:

Result with keys:

lat (float): Latitude.
lon (float): Longitude.
formatted_address (str): Full formatted address.
place_id (str): Google Place ID.
location_type (str): Accuracy — "ROOFTOP", "RANGE_INTERPOLATED", "GEOMETRIC_CENTER", or "APPROXIMATE".
address_components (list): Decomposed address parts.

Returns None if no results found.

Return type:

dict or None

Example

>>> result = geocode("100 S 200 E, Salt Lake City, UT")
>>> if result:
...     print(f"{result['lat']}, {result['lon']}")

geeViz.googleMapsLib.search_places(query: str, lat: float | None = None, lon: float | None = None, radius: float = 5000, max_results: int = 10, included_types: list[str] | None = None) → list[dict[str, Any]][source]¶

Search for places using the Google Places API (New) Text Search.

Parameters:

query (str) – Search text (e.g. “coffee shops”, “gas station”, “Yellowstone visitor center”).
lat (float, optional) – Latitude for location bias.
lon (float, optional) – Longitude for location bias.
radius (float, optional) – Bias radius in meters. Defaults to 5000.
max_results (int, optional) – Maximum results (1-20). Defaults to 10.
included_types (list, optional) – Place type filters (e.g. ["restaurant"], ["gas_station"]).

Returns:

Each dict has keys: name, display_name, address, lat, lon, types, rating, place_id, photo_name (first photo resource name, if any).

Return type:

list of dict

Example

>>> places = search_places("fire station", lat=40.76, lon=-111.89)
>>> for p in places:
...     print(f"{p['display_name']}: {p['address']}")

geeViz.googleMapsLib.search_nearby(lat: float, lon: float, radius: float = 1000, included_types: list[str] | None = None, max_results: int = 10) → list[dict[str, Any]][source]¶

Search for places near a location using Nearby Search (New).

Parameters:

lat (float) – Latitude.
lon (float) – Longitude.
radius (float, optional) – Search radius in meters (max 50000). Defaults to 1000.
included_types (list, optional) – Place type filters (e.g. ["restaurant"]).
max_results (int, optional) – Maximum results (1-20). Defaults to 10.

Returns:

Same format as search_places().

Return type:

list of dict

Example

>>> nearby = search_nearby(40.76, -111.89, radius=2000,
...     included_types=["park"])

geeViz.googleMapsLib.get_place_photo(photo_name: str, max_width: int = 400, max_height: int = 400) → bytes | None[source]¶

Fetch a place photo by its resource name.

Photo names come from search_places() or search_nearby() results (the photo_name field).

Parameters:

photo_name (str) – Photo resource name from a Places API response.
max_width (int, optional) – Maximum width in pixels (1-4800).
max_height (int, optional) – Maximum height in pixels (1-4800).

Returns:

JPEG/PNG image bytes, or None on error.

Return type:

bytes or None

Example

>>> places = search_places("Arches National Park visitor center")
>>> if places and places[0]['photo_name']:
...     photo = get_place_photo(places[0]['photo_name'])

geeViz.googleMapsLib.streetview_metadata(lon: float, lat: float, radius: int = 50, source: str = 'default') → dict[str, Any][source]¶

Check if Street View imagery exists at a location.

This is a free call (no quota consumed).

Parameters:

lon (float) – Longitude in decimal degrees.
lat (float) – Latitude in decimal degrees.
radius (int, optional) – Search radius in meters. Defaults to 50.
source (str, optional) – "default" or "outdoor".

Returns:

Keys: status, pano_id, location, date, copyright.

Return type:

dict

Example

>>> meta = streetview_metadata(-111.89, 40.76)
>>> if meta['status'] == 'OK':
...     print(f"Imagery from {meta['date']}")

geeViz.googleMapsLib.streetview_image(lon: float, lat: float, heading: float = 0, pitch: float = 0, fov: float = 90, size: str = '640x480', radius: int = 50, source: str = 'default') → bytes | None[source]¶

Fetch a Street View static image as JPEG bytes.

Returns None if no imagery exists (checks metadata first).

Parameters:

lon (float) – Longitude.
lat (float) – Latitude.
heading (float, optional) – Compass heading (0=N, 90=E, 180=S, 270=W).
pitch (float, optional) – Camera pitch (positive=up).
fov (float, optional) – Field of view (1-120). Defaults to 90.
size (str, optional) – Image size. Defaults to "640x480".
radius (int, optional) – Search radius. Defaults to 50.
source (str, optional) – "default" or "outdoor".

Returns:

JPEG image bytes.

Return type:

bytes or None

geeViz.googleMapsLib.streetview_images_cardinal(lon: float, lat: float, pitch: float = 0, fov: float = 90, size: str = '640x480', radius: int = 50, source: str = 'default') → dict[str, bytes] | None[source]¶

Fetch Street View images looking N, E, S, and W.

Returns None if no imagery exists.

Parameters:

lon – See streetview_image().
lat – See streetview_image().
pitch – See streetview_image().
fov – See streetview_image().
size – See streetview_image().
radius – See streetview_image().
source – See streetview_image().

Returns:

{"N": bytes, "E": bytes, "S": bytes, "W": bytes}.

Return type:

dict or None

geeViz.googleMapsLib.streetview_panorama(lon: float, lat: float, heading: float = 0, fov: float = 360, pitch: float = 0, size: str = '640x480', radius: int = 50, source: str = 'default') → bytes | None[source]¶

Fetch a wide-angle or full 360° Street View panorama as a stitched image.

The Google Street View Static API caps FOV at 120°. This function automatically splits wider requests into multiple 120° frames and stitches them horizontally using PIL.

Parameters:

lon (float) – Longitude.
lat (float) – Latitude.
heading (float, optional) – Center compass heading of the panorama (0=North). The panorama spans heading - fov/2 to heading + fov/2. Defaults to 0.
fov (float, optional) – Total horizontal field of view in degrees (1–360). Values ≤ 120 are handled in a single frame. Defaults to 360.
pitch (float, optional) – Camera pitch. Defaults to 0.
size (str, optional) – Per-frame size as "WxH". Defaults to "640x480".
radius (int, optional) – Search radius. Defaults to 50.
source (str, optional) – "default" or "outdoor".

Returns:

JPEG bytes of the stitched panorama, or None if no imagery exists.

Return type:

bytes or None

Example

>>> pano = streetview_panorama(-111.80, 40.68, heading=0, fov=360)
>>> if pano:
...     with open("panorama_360.jpg", "wb") as f:
...         f.write(pano)

geeViz.googleMapsLib.interpret_image(image_bytes: bytes, mode: str = 'streetview', prompt: str | None = None, model: str = 'gemini-3.5-flash', temperature: float = 0.3, context: str | None = None) → dict[str, Any][source]¶

Interpret a Street View or static-map image using Google Gemini.

Sends the image to Gemini with instructions to identify and count all notable features. The default prompt is chosen from _INTERPRET_PROMPTS by mode, so the same function handles ground-level Street View, top-down satellite, hybrid, roadmap, and terrain views without the caller needing to write a prompt.

Parameters:

image_bytes (bytes) – JPEG or PNG image bytes.
mode (str, optional) – View type — picks the default prompt. One of "streetview", "satellite-map", "hybrid-map", "roadmap", "terrain". Defaults to "streetview".
prompt (str, optional) – Custom prompt to override the mode’s default. When None, uses _INTERPRET_PROMPTS[mode].
model (str, optional) – Gemini model name. Defaults to "gemini-3.5-flash".
temperature (float, optional) – Sampling temperature. Defaults to 0.3.
context (str, optional) – Additional context prepended to the prompt (e.g. location, date, purpose). Defaults to None.

Returns:

Keys:

description (str): Full text description of the image.
object_counts (str): Markdown table of object counts.
raw_response (str): Complete Gemini response text.
metadata (dict): Token counts (input_tokens, input_text_tokens, input_image_tokens, output_tokens, thought_tokens, cached_tokens, total_tokens), plus model, temperature, mode, prompt_used, and finish_reason.

Return type:

dict

Example

>>> img = streetview_image(-111.80, 40.68, heading=0)
>>> result = interpret_image(img, mode="streetview")
>>> print(result['description'])
>>> print(result['metadata']['total_tokens'])

geeViz.googleMapsLib.label_image(image_bytes: bytes, mode: str = 'streetview', prompt: str | None = None, image_context: str | None = None, location_str: str = '', model: str = 'gemini-3.5-flash', temperature: float = 0.3, max_labels: int = 30, font_size: int = 12) → dict[str, Any] | None[source]¶

Detect and label objects in an image using Gemini vision.

Sends image_bytes to Gemini, asks for JSON-formatted bounding boxes, then draws labeled boxes on the image. Works for any image Gemini can see — Street View panoramas, satellite/nadir tiles, static maps, or arbitrary user-supplied photos.

mode picks a preset from _LABEL_PROMPTS — same modes as interpret_image() (streetview / satellite-map / hybrid-map / roadmap / terrain). Each preset supplies an image_context header (telling Gemini what kind of image this is) and a detection prompt tuned for that view. Nadir modes ask for roof-visible features and skip small ground-level objects that aren’t resolvable from above.

Parameters:

image_bytes (bytes) – JPEG or PNG bytes.
mode (str, optional) – View type. One of "streetview", "satellite-map", "hybrid-map", "roadmap", "terrain". Defaults to "streetview".
prompt (str, optional) – Custom detection body prompt — overrides the mode’s body. Image context header and JSON-format footer are still added around it.
image_context (str, optional) – Override the mode’s context header. Falls back to the mode’s default when None.
location_str (str, optional) – “At X” location text for the header. Empty string skips it.
model (str, optional) – Gemini model. Defaults to "gemini-3.5-flash".
temperature (float, optional) – Sampling temperature. Defaults to 0.3.
max_labels (int, optional) – Maximum objects. Defaults to 30.
font_size (int, optional) – Label font size. Defaults to 12.

Returns:

Keys: image (labeled JPEG bytes), detections (list), summary (markdown table), original (input bytes), metadata (token counts + model + temperature + finish_reason + parse_error if the JSON response needed repair or couldn’t be parsed). Returns None only if PIL can’t decode the input.

Return type:

dict or None

Example

>>> sat = get_static_map(-111.80, 40.68, maptype="satellite", zoom=18)
>>> r = label_image(sat, mode="satellite-map",
...                  location_str="Salt Lake City")
>>> print(r['summary'])
>>> print(r['metadata']['total_tokens'])

geeViz.googleMapsLib.label_streetview(lon: float, lat: float, prompt: str | None = None, heading: float = 0, fov: float = 360, pitch: float = 0, size: str = '640x480', radius: int = 50, source: str = 'default', model: str = 'gemini-3.5-flash', temperature: float = 0.3, max_labels: int = 30, font_size: int = 12) → dict[str, Any] | None[source]¶

Fetch a Street View panorama and label objects on it.

Thin lon/lat wrapper around label_image(). Reverse-geocodes the point for the prompt header, fetches the panorama, calls label_image, and adds location to the returned dict.

Args, return dict, and metadata block match label_image() plus an extra location string. Returns None if no panorama is available at that point.

geeViz.googleMapsLib.streetview_html(lon: float, lat: float, headings: list[float] | None = None, pitch: float = 0, fov: float = 90, size: str = '400x300', radius: int = 50, source: str = 'default', title: str | None = None) → str | None[source]¶

Generate an HTML panel with embedded Street View images.

Parameters:

lon – Coordinates.
lat – Coordinates.
headings (list, optional) – Compass headings. Defaults to [0,90,180,270].
pitch – See streetview_image().
fov – See streetview_image().
size – See streetview_image().
radius – See streetview_image().
source – See streetview_image().
title (str, optional) – Title text. Auto-generated if None.

Returns:

Self-contained HTML string, or None if no imagery.

Return type:

str or None

geeViz.googleMapsLib.get_elevation(lon: float, lat: float) → float | None[source]¶

Get elevation in meters at a geographic location.

Parameters:

lon (float) – Longitude.
lat (float) – Latitude.

Returns:

Elevation in meters above sea level, or None on error.

Return type:

float or None

Example

>>> elev = get_elevation(-111.80, 40.68)
>>> print(f"{elev:.0f} meters")

geeViz.googleMapsLib.get_elevations(points: list[tuple[float, float]]) → list[dict[str, Any]][source]¶

Get elevations for multiple locations in one request.

Parameters:: points (list) – List of (lon, lat) tuples. Max ~500 per request.
Returns:: Each dict has lon, lat, elevation (meters), and resolution (meters).
Return type:: list of dict

Example

>>> pts = [(-111.80, 40.68), (-111.81, 40.69), (-111.82, 40.70)]
>>> elevs = get_elevations(pts)
>>> for e in elevs:
...     print(f"{e['lat']:.4f}: {e['elevation']:.0f}m")

geeViz.googleMapsLib.get_elevation_along_path(points: list[tuple[float, float]], samples: int = 100) → list[dict[str, Any]][source]¶

Get elevation profile along a path.

Samples evenly-spaced points along the path defined by the input waypoints.

Parameters:

points (list) – Path waypoints as (lon, lat) tuples.
samples (int, optional) – Number of sample points. Defaults to 100.

Returns:

Sampled points with lon, lat, elevation, resolution.

Return type:

list of dict

Example

>>> path = [(-111.80, 40.68), (-111.85, 40.72)]
>>> profile = get_elevation_along_path(path, samples=50)

geeViz.googleMapsLib.get_static_map(lon: float, lat: float, zoom: int = 14, size: str = '640x480', maptype: str = 'satellite', markers: list[tuple[float, float]] | None = None, path_points: list[tuple[float, float]] | None = None, path_color: str = 'red', format: str = 'png') → bytes | None[source]¶

Get a static map image centered on a location.

Parameters:

lon (float) – Center longitude.
lat (float) – Center latitude.
zoom (int, optional) – Zoom level (1-21). Defaults to 14.
size (str, optional) – Image size. Defaults to "640x480".
maptype (str, optional) – "satellite", "roadmap", "terrain", or "hybrid". Defaults to "satellite".
markers (list, optional) – List of (lon, lat) marker positions.
path_points (list, optional) – List of (lon, lat) for a path overlay.
path_color (str, optional) – Path line color. Defaults to "red".
format (str, optional) – "png" or "jpg". Defaults to "png".

Returns:

Image bytes.

Return type:

bytes or None

Example

>>> img = get_static_map(-111.80, 40.68, zoom=16, maptype="hybrid")
>>> with open("map.png", "wb") as f:
...     f.write(img)

geeViz.googleMapsLib.get_air_quality(lon: float, lat: float) → dict[str, Any] | None[source]¶

Get current air quality conditions at a location.

Parameters:

lon (float) – Longitude.
lat (float) – Latitude.

Returns:

Keys: aqi (US AQI), category, dominant_pollutant, pollutants (list), date.

Return type:

dict or None

Example

>>> aq = get_air_quality(-111.89, 40.76)
>>> if aq:
...     print(f"AQI: {aq['aqi']} ({aq['category']})")

geeViz.googleMapsLib.get_solar_insights(lon: float, lat: float, quality: str = 'MEDIUM') → dict[str, Any] | None[source]¶

Get rooftop solar potential for the nearest building.

Parameters:

lon (float) – Longitude.
lat (float) – Latitude.
quality (str, optional) – Image quality — "LOW", "MEDIUM", or "HIGH". Defaults to "MEDIUM".

Returns:

Keys: max_panels, max_capacity_watts, max_annual_kwh, roof_area_m2, max_sunshine_hours, carbon_offset_kg.

Return type:

dict or None

Example

>>> solar = get_solar_insights(-111.80, 40.68)
>>> if solar:
...     print(f"Capacity: {solar['max_capacity_watts']:.0f}W")
...     print(f"Annual: {solar['max_annual_kwh']:.0f} kWh")

geeViz.googleMapsLib.snap_to_roads(points: list[tuple[float, float]], interpolate: bool = False) → list[dict[str, Any]][source]¶

Snap GPS points to the nearest road segments.

Parameters:

points (list) – GPS trace as (lon, lat) tuples. Max 100 points.
interpolate (bool, optional) – If True, interpolate additional points along the road between snapped locations. Defaults to False.

Returns:

Snapped points with lon, lat, place_id, and original_index (which input point this snapped from).

Return type:

list of dict

Example

>>> gps = [(-111.80, 40.68), (-111.81, 40.69), (-111.82, 40.70)]
>>> snapped = snap_to_roads(gps)
>>> for s in snapped:
...     print(f"({s['lat']:.5f}, {s['lon']:.5f})")

geeViz.googleMapsLib.nearest_roads(lon: float, lat: float) → list[dict[str, Any]][source]¶

Find the nearest road segments to a point.

Parameters:

lon (float) – Longitude.
lat (float) – Latitude.

Returns:

Nearby road points with lon, lat, place_id.

Return type:

list of dict

Example

>>> roads = nearest_roads(-111.80, 40.68)
>>> for r in roads:
...     print(f"Road at ({r['lat']:.5f}, {r['lon']:.5f})")

geeViz.googleMapsLib.validate_address(address: str, region_code: str = 'US') → dict[str, Any] | None[source]¶

Validate and standardize an address.

Parameters:

address (str) – Address to validate.
region_code (str, optional) – ISO country code. Defaults to "US".

Returns:

Keys: formatted_address, lat, lon, verdict (address quality), components (parsed parts), usps_data (USPS-standardized for US addresses).

Return type:

dict or None

Example

>>> result = validate_address("100 S 200 E, SLC, UT")
>>> print(result['formatted_address'])

geeViz.googleMapsLib.get_timezone(lon: float, lat: float, timestamp: int = 0) → dict[str, Any] | None[source]¶

Get timezone information for a location.

Parameters:

lon (float) – Longitude.
lat (float) – Latitude.
timestamp (int, optional) – Unix timestamp for DST calculation. Defaults to 0 (current time).

Returns:

Keys: timezone_id, timezone_name, utc_offset_seconds, dst_offset_seconds.

Return type:

dict or None

Example

>>> tz = get_timezone(-111.80, 40.68)
>>> print(tz['timezone_id'])  # 'America/Denver'

geeViz.googleMapsLib.reverse_geocode(lon: float, lat: float) → dict[str, Any] | None[source]¶

Convert coordinates to an address (reverse geocoding).

Parameters:

lon (float) – Longitude.
lat (float) – Latitude.

Returns:

Keys: formatted_address, place_id, types, address_components.

Return type:

dict or None

Example

>>> result = reverse_geocode(-111.80, 40.68)
>>> print(result['formatted_address'])

geeViz.googleMapsLib.segment_image(image_bytes: bytes, mode: str = 'streetview', model_variant: str = 'b4', broad_categories: bool = False, model_id: str | None = None) → dict[str, Any][source]¶

Perform pixel-level semantic segmentation on an RGB image.

Uses a SegFormer checkpoint (via transformers). The mode argument picks a preset — class taxonomy + broad-category rollup + color palette matched to what the checkpoint emits.

Modes

"streetview" (default, ground-level) — SegFormer B0–B5 on ADE20K (150 classes). Works out-of-the-box; used for Street View panoramas and oblique photos.
"aerial-urban" (nadir) — Potsdam / Vaihingen 6-class taxonomy (impervious / building / low_vegetation / tree / car / clutter). Good match for Google Static Maps satellite zoom 18-20.
"aerial-landcover" (nadir) — LandCover.ai 5-class taxonomy (background / building / woodland / water / road). Good for rural/mixed landscapes at zoom 15-19.
"aerial-mixed" (nadir) — DeepGlobe 7-class taxonomy (urban_land / agriculture_land / rangeland / forest_land / water / barren_land / unknown). Good for broader landscape at zoom 12-16.

All nadir modes require model_id="user/checkpoint" — community HuggingFace fine-tunes on these datasets exist but their IDs rot, so nothing is hard-coded. Suggested HF search terms are in the error message you’ll get if you forget.

Parameters:

image_bytes (bytes) – JPEG or PNG image bytes.
mode (str, optional) – Preset — one of "streetview", "aerial-urban", "aerial-landcover", "aerial-mixed". Defaults to "streetview".
model_variant (str, optional) – SegFormer size — "b0" (fast, 3.8M params) through "b5" (best, 82M params). Only affects the streetview preset’s auto model_id; ignored when model_id is set explicitly. Defaults to "b4".
broad_categories (bool, optional) – If True, roll fine-grained classes into broad land-cover categories per the mode’s preset. Defaults to False.
model_id (str, optional) – HuggingFace checkpoint override. If None, the preset’s default is used (only streetview has one; nadir modes require this).

Returns:

Keys:

class_map (numpy.ndarray): (H, W) array of class IDs.
class_names (list): Class name for each ID.
colored_image (bytes): JPEG with colored overlay + legend.
legend (dict): {class_name: hex_color} for classes present.
summary (str): Markdown table of area percentages.
area_pct (dict): {class_name: float} area percentages.
metadata (dict): mode, model_id, model_variant, orientation (ground/nadir), classes_count, and broad_categories flag.

Return type:

dict

Example

>>> pano = streetview_panorama(-111.80, 40.68, fov=360)
>>> seg = segment_image(pano)                     # streetview default
>>> sat = get_static_map(-111.80, 40.68, maptype="satellite", zoom=19)
>>> seg2 = segment_image(sat, mode="aerial-urban",
...                        model_id="user/segformer-potsdam-b4")
>>> print(seg['summary'])

geeViz.googleMapsLib.segment_streetview(lon: float, lat: float, heading: float = 0, fov: float = 360, pitch: float = 0, size: str = '640x480', radius: int = 50, source: str = 'default', model_variant: str = 'b4', broad_categories: bool = True) → dict[str, Any] | None[source]¶

Fetch a Street View panorama and segment it with SegFormer.

Convenience wrapper that combines streetview_panorama() and segment_image().

Parameters:

lon – Coordinates.
lat – Coordinates.
heading – See streetview_panorama().
fov – See streetview_panorama().
pitch – See streetview_panorama().
size – See streetview_panorama().
radius – See streetview_panorama().
source – See streetview_panorama().
model_variant (str, optional) – SegFormer size. Defaults to "b4".
broad_categories (bool, optional) – Merge into land cover categories. Defaults to True.

Returns:

Same as segment_image() plus original (raw panorama bytes) and location (address string). Returns None if no Street View coverage.

Return type:

dict or None

Example

>>> result = segment_streetview(-111.80, 40.68, fov=360)
>>> if result:
...     print(result['summary'])
...     with open("segmented.jpg", "wb") as f:
...         f.write(result['colored_image'])