i.hyper.metadata
View and manage hyperspectral metadata for 3D raster maps.
i.hyper.metadata map=name [operation=string] [format=string] [wavelength_range=string] [resolve_names=string] [extended_select=string [,string,...]] [--verbose] [--quiet] [--qq] [--ui]
Example:
i.hyper.metadata map=name
grass.tools.Tools.i_hyper_metadata(map, operation="summary", format="json", wavelength_range=None, resolve_names="no", extended_select="all", verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.i_hyper_metadata(map="name", format="json")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
grass.script.parse_command("i.hyper.metadata", map, operation="summary", format="json", wavelength_range=None, resolve_names="no", extended_select="all", verbose=None, quiet=None, superquiet=None)
Example:
gs.parse_command("i.hyper.metadata", map="name", format="json")
Parameters
map=name [required]
Input 3D raster map
operation=string
Operation to perform
Allowed values: summary, full, extended, bands, history, validate
Default: summary
summary: Print concise metadata summary
full: Print full metadata for current map
extended: Print selected parts of extended_metadata
bands: List source bands
history: Show full recursive ordered history
validate: Check metadata and lineage consistency
format=string
Output format
Allowed values: json, text, csv
Default: json
wavelength_range=string
Filter bands by wavelength range (e.g., 400-700)
resolve_names=string
Resolve map names by dataset_id for display (full and history)
Allowed values: yes, no
Default: no
extended_select=string [,string,...]
Selector for operation=extended: all, branch, or dot path (e.g., acquisition,geometry.sun_zenith_deg)
Default: all
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
map : str, required
Input 3D raster map
Used as: input, raster_3d, name
operation : str, optional
Operation to perform
Allowed values: summary, full, extended, bands, history, validate
summary: Print concise metadata summary
full: Print full metadata for current map
extended: Print selected parts of extended_metadata
bands: List source bands
history: Show full recursive ordered history
validate: Check metadata and lineage consistency
Default: summary
format : str, optional
Output format
Allowed values: json, text, csv
Default: json
wavelength_range : str, optional
Filter bands by wavelength range (e.g., 400-700)
resolve_names : str, optional
Resolve map names by dataset_id for display (full and history)
Allowed values: yes, no
Default: no
extended_select : str | list[str], optional
Selector for operation=extended: all, branch, or dot path (e.g., acquisition,geometry.sun_zenith_deg)
Default: all
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.
Raises:
grass.tools.ToolError: When the tool ended with an error.
map : str, required
Input 3D raster map
Used as: input, raster_3d, name
operation : str, optional
Operation to perform
Allowed values: summary, full, extended, bands, history, validate
summary: Print concise metadata summary
full: Print full metadata for current map
extended: Print selected parts of extended_metadata
bands: List source bands
history: Show full recursive ordered history
validate: Check metadata and lineage consistency
Default: summary
format : str, optional
Output format
Allowed values: json, text, csv
Default: json
wavelength_range : str, optional
Filter bands by wavelength range (e.g., 400-700)
resolve_names : str, optional
Resolve map names by dataset_id for display (full and history)
Allowed values: yes, no
Default: no
extended_select : str | list[str], optional
Selector for operation=extended: all, branch, or dot path (e.g., acquisition,geometry.sun_zenith_deg)
Default: all
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
DESCRIPTION
i.hyper.metadata reads and manages metadata for hyperspectral 3D raster maps created by the i.hyper toolchain.
Metadata is loaded from hyper.json.
NOTES
Supported operations:
summary: concise metadata summary for current datasetfull: full metadata object for current datasetextended: selectedextended_metadataonly (all, branch, key path, or multiple selectors; resolved through lineage inheritance for derived datasets)bands: list source bands (optionally filtered by wavelength range)history: recursive aggregated lineage history, ordered by timestamp (usesinput_datasets_metadatasnapshots when referenced inputs are unavailable in current LOCATION)validate: metadata and lineage consistency checks
Output format (format) is global for all operations:
json(default)textcsv
For full and history, resolve_names=yes resolves inputs/outputs
map names from current maps by dataset_id (display only; stored command
is unchanged).
For operation=extended, option extended_select= supports:
all(default): fullextended_metadata- one branch (e.g.,
acquisition) - one key path (e.g.,
geometry.sun_zenith_deg) - multiple selectors at once (comma-separated), e.g.,
acquisition,geometry.sun_zenith_deg,processing - selectors with
extended_metadata.prefix are also accepted (for example,extended_metadata.geometry.sun_zenith_deg)
Selectors are evaluated on resolved extended_metadata (current dataset
overrides plus inherited values from lineage).
Dataset provenance is stored in top-level key derived:
derived=false: original imported datasetderived=true: any dataset created from other dataset(s)
API (CLI)
Main options:
map=: inputraster_3dmapoperation=:summary|full|extended|bands|history|validateformat=:json|text|csvresolve_names=:yes|no(forfullandhistory)wavelength_range=: foroperation=bands(example:400-700)extended_select=: foroperation=extended(all/branch/path/multiple)
API examples:
::: code
# Full metadata as JSON
i.hyper.metadata map=my_cube operation=full format=json
# Bands as CSV in 700-900 nm
i.hyper.metadata map=my_cube operation=bands wavelength_range=700-900 format=csv
# One extended branch
i.hyper.metadata map=my_cube operation=extended extended_select=geometry
# Multiple extended selectors
i.hyper.metadata map=my_cube operation=extended \
extended_select=acquisition,geometry.sun_zenith_deg,atmosphere.aod_550
:::
JSON metadata structure
Imported datasets store full dataset description at top level. Derived datasets store mandatory provenance keys and only local overrides.
::: code { "schema_version": "1.0", "dataset_id": "5bc6cb5c55b44993afeb78f2da5c8ccf", "derived": true, "processing_history": [ { "command": "i.hyper.preproc input=enmap output=enmap_sg steps=sav_gol window_length=7 polyorder=3", "timestamp": "2026-03-25T12:41:05.281173", "inputs": [{"id": "7da4f3e02b8f4ef2bc2a06fb0fe4bb8d", "map_name": "enmap@PERMANENT"}], "outputs": [{"id": "5bc6cb5c55b44993afeb78f2da5c8ccf", "map_name": "enmap_sg@PERMANENT"}] } ], "input_datasets_metadata": { "7da4f3e02b8f4ef2bc2a06fb0fe4bb8d": { "...": "full parent metadata snapshot" } } } :::
Derived dataset required top-level keys:
schema_versiondataset_idderivedprocessing_history
Optional local override keys in derived datasets:
data_typesensorwavelength_unitsradiometric_quantityradiometric_unitsregionbandsextended_metadatadimensionality_reduction(written only for outputs where dimensionality reduction is applied)
Inheritance rule:
- if an optional key is missing in derived dataset, value is inherited through lineage
- for multiple direct inputs, value is inherited only when all direct inputs resolve to the same value
dimensionality_reductionis not inherited; it is present only when DR is applied for the current output dataset
Extended Metadata Branches
Common unified branches:
acquisitiongeometryradiometryatmospherequalityprocessinguncertainty
Product-specific branches:
enmapprismatanager
Dimensionality reduction metadata is stored in top-level
dimensionality_reduction, not in extended_metadata.processing.
For derived datasets, top-level input_datasets_metadata stores full metadata
snapshots for all input datasets recursively to origin, keyed by dataset_id.
Embedded snapshots exclude nested input_datasets_metadata.
operation=history uses these snapshots when referenced input metadata are
unavailable in the current LOCATION.
Unified branches store cross-product keys. Product-specific branches store source product keys used to derive unified values (provenance). The same value may appear in both locations by design.
Only unified geometry keys under extended_metadata.geometry are used.
For key mapping and provenance rules, see:
extended_metadata_unification.md
EXAMPLES
View metadata summary:
::: code
i.hyper.metadata map=my_hyper_cube operation=summary format=text
:::
Show bands in visible range:
::: code
i.hyper.metadata map=my_hyper_cube operation=bands wavelength_range=400-700
:::
Show full recursive history with current map names:
::: code
i.hyper.metadata map=my_hyper_cube operation=history resolve_names=yes
:::
Show all extended metadata:
::: code
i.hyper.metadata map=my_hyper_cube operation=extended extended_select=all
:::
Show one specific extended metadata key:
::: code
i.hyper.metadata map=my_hyper_cube operation=extended \
extended_select=geometry.sun_zenith_deg
:::
Show selected branches and key paths at the same time:
::: code
i.hyper.metadata map=my_hyper_cube operation=extended \
extended_select=acquisition,geometry.sun_zenith_deg,processing
:::
Show ATCORR-ready metadata subset (geometry + atmosphere + timing):
::: code
i.hyper.metadata map=my_hyper_cube operation=extended \
extended_select=acquisition.start_time_utc,acquisition.day_of_year,geometry.sun_zenith_deg,geometry.sun_azimuth_deg,geometry.view_zenith_deg,geometry.view_azimuth_deg,geometry.relative_azimuth_deg,atmosphere.aod_550,atmosphere.h2o_g_cm2,atmosphere.ozone_du \
format=json
:::
SEE ALSO
i.hyper, i.hyper.import, i.hyper.preproc, i.hyper.explore
AUTHORS
GRASS Development Team Alen Mangafić and Tomaž Žagar, Geodetic Institute of Slovenia Anna Petrášová, NCSU GeoForAll Lab
SOURCE CODE
Available at: i.hyper.metadata source code
(history)
Latest change: Wednesday May 20 19:27:36 2026 in commit 64c6df5