geeViz.eeCatalogHelpers

Offline-safe planning and metadata helpers for Earth Engine catalogs.

Only standard-library modules are imported at load time. Raster operations require GDAL at call time; ingestion lazily imports geeViz.assetManagerLib.

geeViz.eeCatalogHelpers.clean_text(value: str | None) → str[source]

Normalize BOM/whitespace and return an empty string for nulls.

geeViz.eeCatalogHelpers.normalize_for_matching(value: str | None, null_tokens: set[str] | None = None) → str[source]

Normalize text and collapse common null-like tokens to empty strings.

geeViz.eeCatalogHelpers.choose_preferred_column(header: Sequence[str], preferred_candidates: Sequence[str]) → str | None[source]

Return the first preferred candidate present in a header list.

geeViz.eeCatalogHelpers.value_to_int(value: Any) → int | None[source]

Convert text-like numeric values into ints, returning None when unavailable.

geeViz.eeCatalogHelpers.color_from_row(row: Mapping[str, Any]) → str[source]

Parse ‘#RRGGBB’ or RGB triplets from a row and return uppercase hex.

class geeViz.eeCatalogHelpers.JsonnetLiteral(expression: str)[source]

Bases: object

Wrapper for raw Jsonnet expressions that must not be quoted.

geeViz.eeCatalogHelpers.is_jsonnet_identifier(key: str) → bool[source]

Return True when a key can be written unquoted in Jsonnet.

Reserved words are excluded because they cannot appear as bare field names.

geeViz.eeCatalogHelpers.render_jsonnet_value(value: Any, indent: int = 0, indent_step: int = 2) → str[source]

Render Python values to formatted Jsonnet text.

geeViz.eeCatalogHelpers.replace_unit_literals(value: Any) → Any[source]

Convert known units expressions (for example ‘units.percent’) to literals.

geeViz.eeCatalogHelpers.render_jsonnet_catalog_blocks(eo_bands: list[dict[str, Any]], gee_visualizations: list[dict[str, Any]] | None = None) → dict[str, str][source]

Render Jsonnet-ready blocks for Earth Engine catalog metadata.

geeViz.eeCatalogHelpers.render_jsonnet_table_blocks(gee_schema: list[dict[str, Any]], gee_visualizations: list[dict[str, Any]] | None = None, feature_view_ingestion_params: dict[str, Any] | None = None) → dict[str, str][source]

Render Jsonnet blocks used by Earth Engine table catalog entries.

geeViz.eeCatalogHelpers.coerce_nodata_value(value: Any) → Any[source]

Normalize nodata values to native numeric types where possible.

geeViz.eeCatalogHelpers.resolve_lookup_value(record: dict[str, Any], value_key: str, default: Any = None) → Any[source]

Resolve a value key with optional alias support from a lookup record.

geeViz.eeCatalogHelpers.resolve_property_value(spec: Any, context: dict[str, Any]) → Any[source]

Resolve one property spec item using raw, callable, or lookup syntax.

geeViz.eeCatalogHelpers.build_image_properties(image_property_fields: list[str], image_property_lookups: dict[str, Any], image_context: dict[str, Any]) → dict[str, Any][source]

Build image properties from declarative field and lookup mappings.

geeViz.eeCatalogHelpers.build_ingest_entry(band_name: str, pyramiding_policy: str, gcs_uri: str, nodata_value: Any) → dict[str, Any][source]

Build one normalized geeViz multi-image ingest entry.

class geeViz.eeCatalogHelpers.BandProfile(name: str, source_suffix: str, source_location: str, pyramiding_policy: str, valid_min: float, valid_max: float, data_type: str, conversion: str, source_valid_values: tuple[float, ...] | None, value_map: Mapping[float, int] | None, description: str)[source]

Bases: object

Metadata contract for one band in a multi-band image.

name: str
source_suffix: str
source_location: str
pyramiding_policy: str
valid_min: float
valid_max: float
data_type: str
conversion: str
source_valid_values: tuple[float, ...] | None
value_map: Mapping[float, int] | None
description: str
class geeViz.eeCatalogHelpers.PlannedBand(profile: BandProfile, source_path: Path, gcs_uri: str, nodata_value: int | float | None)[source]

Bases: object

One local source raster and its planned ingest settings.

as_ingest_entry() → dict[str, Any][source]
profile: BandProfile
source_path: Path
gcs_uri: str
nodata_value: int | float | None
class geeViz.eeCatalogHelpers.PlannedImage(image_name: str, asset_id: str, bands: tuple[PlannedBand, ...], properties: Mapping[str, Any])[source]

Bases: object

A deterministic Earth Engine image ingest plan.

as_preview() → dict[str, Any][source]
image_name: str
asset_id: str
bands: tuple[PlannedBand, ...]
properties: Mapping[str, Any]
geeViz.eeCatalogHelpers.load_band_profiles(path: str | Path) → tuple[BandProfile, ...][source]

Load and validate an ordered JSON band-profile list.

geeViz.eeCatalogHelpers.join_gcs_uri(prefix: str, object_name: str) → str[source]

Join a gs:// prefix and object name without changing identifier text.

geeViz.eeCatalogHelpers.build_planned_bands(profiles: Iterable[BandProfile], source_paths: Mapping[str, Path], gcs_prefix: str, nodata_values: Mapping[str, Any], object_prefix: str = '') → tuple[PlannedBand, ...][source]

Build ordered manifest bands from explicit source paths.

geeViz.eeCatalogHelpers.write_manifest_preview(images: Iterable[PlannedImage], path: str | Path) → None[source]

Write deterministic, human-reviewable ingest plans.

geeViz.eeCatalogHelpers.ingest_planned_image(image: PlannedImage, overwrite: bool = False) → Any[source]

Lazily submit ordered bands; requires the geeViz Earth Engine runtime.

Properties are copied before submission so the caller’s dictionary is never modified.

geeViz.eeCatalogHelpers.build_image_dict(image_folder: str | Path, name_format: str, pyramiding_policies: Mapping[str, Any], nodata_values: Mapping[str, Any], gcs_prefix: str, normalize_attribute_name: Callable[[str], str] | None = None, include_attribute: Callable[[str], bool] | None = None, resolve_duplicate_band: Callable[[str, Path, Path], Path | None] | None = None) → dict[str, dict[str, Any]][source]

Discover matching TIFFs recursively and build geeViz ingest entries.

name_format must contain an {attribute} placeholder. Dataset-owned normalization and filtering rules can be supplied as callbacks.

geeViz.eeCatalogHelpers.catalog_filename(asset_id: str, suffix: str = '.jsonnet') → str[source]

Return the standard catalog filename for an Earth Engine asset ID.

geeViz.eeCatalogHelpers.write_text_artifacts(output_dir: Path, artifacts: Mapping[Path | str, str]) → list[Path][source]

Write a deterministic set of UTF-8 text artifacts below output_dir.

geeViz.eeCatalogHelpers.infer_table_field_type(values: Iterable[str]) → str[source]

Infer a table field type from all populated CSV values.

geeViz.eeCatalogHelpers.build_table_schema_from_csv(csv_path: Path, field_descriptions: Mapping[str, str], *, type_overrides: Mapping[str, str] | None = None) → list[dict[str, object]][source]

Build a Jsonnet-ready gee:schema from a CSV table.

Descriptions are required for every CSV field. Type overrides accept int, double, and string; other fields are inferred from all populated CSV values.

geeViz.eeCatalogHelpers.convert_tif_to_cog(local_tif: str | Path, cog_path: str | Path | None = None, overwrite: bool = True, options: list[str] | None = None) → None[source]

Convert a GeoTIFF using gdal_translate and atomically replace its output.

geeViz.eeCatalogHelpers.confirm_cog(local_tif: str | Path) → bool[source]

Check gdalinfo output for the COG layout marker.

geeViz.eeCatalogHelpers.validate_tif_for_ingest(local_tif: str | Path) → None[source]

Fail fast when a TIFF cannot be opened and sampled by optional GDAL.

Modules

catalog

Catalog artifact naming and writing.

discovery

Recursive TIFF discovery.

ingest

Ingestion planning dataclasses and the lazy planned-image adapter.

jsonnet

Jsonnet literal rendering helpers.

parsing

Header, integer, and color parsing helpers.

properties

Image property and nodata resolution helpers.

raster

Optional GDAL-backed raster helpers (GDAL is loaded only when called).

table_metadata

Table schema inference from CSV files.

text

Text normalization helpers.