Trait gdal::Metadata

source · 
pub trait Metadata: MajorObject {
    // Provided methods
    fn description(&self) -> Result<String> { ... }
    fn metadata_domains(&self) -> Vec<String> { ... }
    fn metadata_domain(&self, domain: &str) -> Option<Vec<String>> { ... }
    fn metadata_item(&self, key: &str, domain: &str) -> Option<String> { ... }
    fn set_metadata_item(
        &mut self,
        key: &str,
        value: &str,
        domain: &str
    ) -> Result<()> { ... }
    fn set_description(&mut self, description: &str) -> Result<()> { ... }
    fn metadata(&self) -> MetadataIter<'_>
       where Self: Sized { ... }
}
Expand description

General-Purpose Metadata API

The Metadata trait exposes a simple, general-purpose metadata model for various types in the GDAL datamodel, including Driver, Dataset, RasterBand, and Layer. These data are comprised of key-value strings, organized under parent keys called “domains”. This includes the empty-string ("") root domain. There’s even an xml: domain with it’s own world of content.

GDAL’s metadata structures could be seen as peculiar, and there are driver-specific nuances to navigate, but in scientifically rich datasets, or projects aiming for archival-quality content, its capabilities can fulfill sophisticated requirements.

Reading the Metadata section in the GDAL Raster Data Model document can help if you need to deep, fine-grained metadata access, or examples on how it is used.

Example

use gdal::{Dataset, Metadata};
let dataset = Dataset::open("fixtures/tinymarble.tif")?;
// `description` on a `Dataset` is usually the file name.
let desc = dataset.description()?;
dbg!(desc);

// `IMAGE_STRUCTURE` is one of the standard domains
let md_domain = "IMAGE_STRUCTURE";
// The `INTERLEAVE` key provides a hint as to how pixel data is organized
let md_key = "INTERLEAVE";
// NB: `domain` comes **after** the `key`
let interleave = dataset.metadata_item(&md_key, &md_domain);
dbg!(interleave);

Provided Methods§

source

fn description(&self) -> Result<String>

For most crate::Datasets, method returns this is the originating filename. For crate::raster::RasterBands it is a description (if supported) or "".

Example
use gdal::{Dataset, Metadata};
let dataset = Dataset::open("fixtures/tinymarble.tif")?;
// `description` on a `Dataset` is usually the file name.
let desc = dataset.description()?;
assert_eq!(desc, "fixtures/tinymarble.tif");
source

fn metadata_domains(&self) -> Vec<String>

Metadata in GDAL is partitioned into namespaces, knows as “domains” in the GDAL Data Model. GDAL types with metadata (a.k.a. “Major Objects”) have a default or “root” domain identified by the empty string (""). Specific “Major Object” types may have other conventionally recognized domains. For example, in raster Datasets you may come across the domains SUBDATASETS, IMAGE_STRUCTURE, RPC, IMAGERY, xml:, etc.

Example
use gdal::{Dataset, Metadata};
let dataset = Dataset::open("fixtures/labels.tif")?;
assert!(dataset.metadata_domains().contains(&"IMAGE_STRUCTURE".to_string()));
source

fn metadata_domain(&self, domain: &str) -> Option<Vec<String>>

Get all the metadata values within the given domain. Returns None if domain is not defined. Entries in the returned Vec<String> are formatted as “Name=value” pairs

Arguments
  • domain – the domain of interest. Use "" for the default domain.
Example
use gdal::{Dataset, Metadata};
let dataset = Dataset::open("fixtures/labels.tif")?;
assert_eq!(dataset.metadata_domain("IMAGE_STRUCTURE").unwrap(),vec!["INTERLEAVE=BAND"] );
source

fn metadata_item(&self, key: &str, domain: &str) -> Option<String>

Get a single metadata entry, as indicated by key and domain.

Example
use gdal::{Dataset, Metadata};
let dataset = Dataset::open("fixtures/labels.tif")?;
assert_eq!(dataset.metadata_item("INTERLEAVE", "IMAGE_STRUCTURE").unwrap(),"BAND");
source

fn set_metadata_item( &mut self, key: &str, value: &str, domain: &str ) -> Result<()>

Set a metadata item in given domain at given key.

Example
use gdal::{DriverManager, Metadata};
let mut driver = DriverManager::get_driver_by_name("MEM")?;
let (domain, key, value) = ("FOOBAR", "fake", "data");
assert!(driver.metadata_domain(domain).is_none());
driver.set_metadata_item(key, value, domain)?;
assert!(driver.metadata_domain(domain).is_some());
assert_eq!(driver.metadata_item(key, domain), Some(value.to_string()));
source

fn set_description(&mut self, description: &str) -> Result<()>

For Datasets this sets the dataset name; normally application code should not set the “description” for GDALDatasets. For RasterBands it is actually a description (if supported) or "".

source

fn metadata(&self) -> MetadataIter<'_>where Self: Sized,

Get an iterator over metadata entries, across all domains.

Example
use gdal::{Dataset, Metadata, MetadataEntry};
let dataset = Dataset::open("fixtures/tinymarble.tif")?;
for MetadataEntry { domain, key, value } in dataset.metadata() {
  let domain = if domain == "" { "DEFAULT".to_string() } else { domain };
  println!("{domain}: {key}={value}");
}

Output:

IMAGE_STRUCTURE: INTERLEAVE=PIXEL
DEFAULT: AREA_OR_POINT=Area
...
DERIVED_SUBDATASETS: DERIVED_SUBDATASET_1_NAME=DERIVED_SUBDATASET:LOGAMPLITUDE:fixtures/tinymarble.tif
DERIVED_SUBDATASETS: DERIVED_SUBDATASET_1_DESC=log10 of amplitude of input bands from fixtures/tinymarble.tif

Implementors§