Geometry table support

The geometry_support subpackage builds the geometry tables. The package __init__ re-exports the principal entry points and classes; the submodules below hold the implementation.

metadata_tools.geometry_support

The package __init__ re-exports the names below from the submodules; each is documented on its submodule’s page.

metadata_tools.geometry_support.process

get_args(host: str | None = None, selection: str | None = None, exclude: list[str] | None = None, sampling: int = 8) → ArgumentParser

Build the argument parser for geometric metadata.

Parameters:

• host – Host name, e.g. ‘GOISS’.

• selection – A string containing “S” to generate summary files and “D” to generate detailed files.

• exclude – List of volumes to exclude.

• sampling – Pixel sampling density.

Returns:

Parser containing the argument specifications.

process_tables(template_name: str, volumes: list[str] | None = None, selection: str | None = None, exclude: list[str] | None = None, sampling: int = 8, glob: str | None = None, index_glob: str | None = None, args: Namespace | None = None, task_file: str | None = None, task_list_only: bool = False) → None

Create geometry tables for a collection of volumes.

Parameters:

• template_name – Name of index template.

• volumes – List of volume ids to process. Overrides args.volumes.

• selection – A string containing “S” to generate summary files and “D” to generate detailed files.

• exclude – List of volumes to exclude.

• sampling – Pixel sampling density.

• glob – Glob pattern for data files.

• index_glob – Glob pattern for index files.

• args – Parsed arguments.

• task_file – Name of tasks file. This file is overwritten. If not given, tasks are provided via the task_source generator.

• task_list_only – If True, a task list is created and no processing is performed. If task_file is given, then the task list is written to that file. Otherwise, the task list is accessed via the task_source generator.

metadata_tools.geometry_support.suite

class Suite(input_dir: str | Path | FCPath, output_dir: str | Path | FCPath, template_path: str | Path | FCPath, metadata_dir: str | Path | FCPath | None = None, selection: str = '', glob: str | None = None, index_glob: str | None = None, first: int | None = None, sampling: int = 8)

Bases: object

Class describing the suite of geometry tables for a single volume.

add(records: list[Record]) → None

Add a row to all tables.

Parameters:

records – Records describing the rows to add, one for each processing level.

add_tables(output_dir: str | Path | FCPath, level: str) → None

Add a set of tables.

Parameters:

• output_dir – Directory in which to write the geometry files.

• level – ‘summary’ or ‘detailed’.

create(labels_only: bool = False, pattern: str | None = None) → None

Process the volume and write a suite of geometry files.

Parameters:

• labels_only – If True, labels are generated for any existing geometry tables.

• pattern – Glob pattern for sub-selecting files to process.

static get_override(record: Record, qualifier: str, name: str | None = None) → list[dict[str, Any]]

Build a dictionary of column overrides.

Parameters:

• record – Any Record.

• qualifier – ‘sky’, ‘sun’, ‘ring’, or ‘body’.

• name – Name identifying a specific column description.

Returns:

Dicts containing override names and values for each column.

static get_overrides(record: Record) → dict[str, list[dict[str, Any]]]

Build a dictionary of column overrides keyed by qualifier.

Parameters:

record – Any Record.

Returns:

Dicts containing override names and values for each column, keyed by qualifier.

make_records(index: int) → list[Record]

Add a record for each processing level.

Parameters:

index – Row index.

Returns:

One record for each processing level.

write(labels_only: bool = False) → None

Write all tables and their labels.

Parameters:

labels_only – If True, labels are generated for any existing geometry tables.

metadata_tools.geometry_support.record

class Record(observation: Any, volume_id: str, meshgrids: dict[str, Any], sampling: int, level: str)

Bases: object

Class describing a single geometry record, i.e., a single row in a table.

add(qualifier: str, *, name: str | None = None, target: str | None = None, tiles: list[Any] | tuple[Any, ...] | None = None, tiling_min: int = 100, ignore_shadows: bool = False, start_index: int = 1, allow_zero_rows: bool = True, no_mask: bool = False, no_body: bool = False) → list[str]

Generate the geometry for one row, given a list of column descriptions.

The tiles argument supports detailed listings where a geometric region is broken down into separate subregions. If the tiles argument is empty (which is the default), then this routine writes a summary file.

If the tiles argument is not empty, then the routine writes a detailed file, which generally contains one record for each non-empty subregion. The tiles argument must be a list of boolean backplane keys, each equal to True for the pixels within the subregion. An additional column is added before the geometry columns, containing the index value of the associated tile.

The first backplane in the list is treated differently. It should evaluate to an area roughly equal to the union of all the other backplanes. It is used to ensure that tiling is suppressed when the region to be tiled is too small. If the number of meshgrid samples that are equal to True in this backplane is smaller than the limit specified by argument tiling_min, then no detailed record is written.

In a summary listing, this routine writes one record per call, even if all values are null. In a detailed listing, only records associated with non-empty regions of the meshgrid are written.

Parameters:

• qualifier – ‘sky’, ‘sun’, ‘ring’, or ‘body’.

• name – Name identifying a specific column description.

• target – Optionally, the target name to write into the record.

• tiles – An optional list of boolean backplane keys, used to support the generation of detailed tabulations instead of summary tabulations. See details above.

• tiling_min – The lower limit on the number of meshgrid points in a region before that region is subdivided into tiles.

• ignore_shadows – True to ignore any mask constraints applicable to shadowing or to the sunlit faces of surfaces.

• start_index – Index to use for first subregion. Default 1.

• allow_zero_rows – True to allow the function to return no rows. If False, a row filled with null values will be returned if necessary.

• no_mask – True to suppress the use of a mask.

• no_body – True to suppress body prefixes.

Returns:

The formatted output rows.

static get_backplane_key(column_desc: Any) → str

Extract the backplane key from the column description.

Parameters:

column_desc – A column description; its first element is the event key (a tuple whose first element is the backplane key, or the backplane key itself).

Returns:

The backplane key.

get_key_map(columns: list[str], qualifier: str) → tuple[list[Any], list[str]]

Construct the mapping between backplane keys and column values.

Parameters:

• columns – One str for each column.

• qualifier – ‘sky’, ‘sun’, ‘ring’, or ‘body’.

Returns:

A tuple (backplane keys, column values).

postprocess(columns: list[str], qualifier: str) → list[str]

Process the completed record.

Parameters:

• columns – One str for each column.

• qualifier – ‘sky’, ‘sun’, ‘ring’, or ‘body’.

Returns:

The processed columns.

metadata_tools.geometry_support.tables

class BodyTable(output_dir: str | Path | FCPath | None = None, template_path: str | Path | FCPath | None = None, **kwargs: Any)

Bases: Table

Class describing a body geometry table.

add(record: Record) → None

Add a Body row.

Parameters:

record – Record describing the row to add.

class InventoryTable(output_dir: str | Path | FCPath | None = None, template_path: str | Path | FCPath | None = None, **kwargs: Any)

Bases: Table

Class describing an inventory geometry table.

add(record: Record) → None

Add an Inventory row.

Parameters:

record – Record describing the row to add.

class RingTable(output_dir: str | Path | FCPath | None = None, template_path: str | Path | FCPath | None = None, **kwargs: Any)

Bases: Table

Class describing a ring geometry table.

add(record: Record) → None

Add a Ring row.

Parameters:

record – Record describing the row to add.

class SkyTable(output_dir: str | Path | FCPath | None = None, template_path: str | Path | FCPath | None = None, **kwargs: Any)

Bases: Table

Class describing a sky geometry table.

add(record: Record) → None

Add a Sky row.

Parameters:

record – Record describing the row to add.

class SunTable(output_dir: str | Path | FCPath | None = None, template_path: str | Path | FCPath | None = None, **kwargs: Any)

Bases: Table

Class describing a sun geometry table.

add(record: Record) → None

Add a Sun row.

Parameters:

record – Record describing the row to add.

metadata_tools.geometry_support.prep

append_body_prefix(prefix_columns: list[str], body: str | None, length: int) → None

Append a body name to the column prefixes.

Parameters:

• prefix_columns – A list of the strings to appear at the beginning of the row, up to and including the file specification name. Each individual string should already be enclosed in quotes.

• body – Body name to append.

• length – The character width of a column to contain body names.

prep_row(record: Record, prefixes: list[str], backplane: Any, blocker: str | None, column_descs: Any, *, primary: str | None = None, target: str | None = None, name_length: int = 12, tiles: list[Any] | tuple[Any, ...] | None = None, tiling_min: int = 100, ignore_shadows: bool = False, start_index: int = 1, allow_zero_rows: bool = True, no_mask: bool = False, no_body: bool = False) → tuple[list[list[str]], list[list[dict[str, Any]]]]

Generate the geometry and return a list of lists of strings.

The inner list contains string representations for each column in one row of the output file. These will be concatenated with commas between them and written to the file. The outer list contains one list for each output row. The number of output rows can be zero or more.

The tiles argument supports detailed listings where a geometric region is broken down into separate subregions. If the tiles argument is empty (which is the default), then this routine writes a summary file.

If the tiles argument is not empty, then the routine writes a detailed file, which generally contains one record for each non-empty subregion. The tiles argument must be a list of boolean backplane keys, each equal to True for the pixels within the subregion. An additional column is added before the geometry columns, containing the index value of the associated tile.

The first backplane in the list is treated differently. It should evaluate to an area roughly equal to the union of all the other backplanes. It is used as an overlay to all subsequent tiles.

In a summary listing, this routine writes one record per call, even if all values are null. In a detailed listing, only records associated with non-empty regions of the meshgrid are written.

Parameters:

• record – The geometry record.

• prefixes – A list of the strings to appear at the beginning of the line, up to and including the file specification name. Each individual string should already be enclosed in quotes.

• backplane – Backplane for the observation.

• blocker – The name of one body that may be able to block or shadow other bodies.

• column_descs – A list of column descriptions.

• primary – Name of primary body, uppercase, e.g., “SATURN”.

• target – Optionally, the target name to write into the record.

• name_length – The character width of a column to contain body names. If zero (which is the default), then no name is written into the record.

• tiles – An optional list of boolean backplane keys, used to support the generation of detailed tabulations instead of summary tabulations. See details above.

• tiling_min – The lower limit on the number of meshgrid points in a region before that region is subdivided into tiles.

• ignore_shadows – True to ignore any mask constraints applicable to shadowing or to the sunlit faces of surfaces.

• start_index – Index to use for first subregion. Default 1.

• allow_zero_rows – True to allow the function to return no rows. If False, a row filled with null values will be returned if necessary.

• no_mask – True to suppress the use of a mask.

• no_body – True to suppress body prefixes.

Returns:

A tuple (rows, overrides), where rows holds the strings comprising the resulting rows, and overrides holds dicts of column entries to override in the label, one dict for each column, not including prefix columns.

metadata_tools.geometry_support.masks

construct_excluded_mask(backplane: Any, target: str, primary: str | None, mask_desc: tuple[str, str, str], *, blocker: str | None = None, ignore_shadows: bool = True) → ndarray[tuple[Any, ...], dtype[bool]] | bool

Return a mask of excluded pixels for the given target.

The mask is built from the specified target, maskers and shadowers.

Parameters:

• backplane – The backplane defining the target surface.

• target – The name of the target surface.

• primary – Name of primary, e.g., “SATURN”.

• mask_desc – A tuple (masker, shadower, face), where masker is a string identifying what surfaces can obscure the target, formed by concatenating “P” to let the planet obscure the target, “R” to let the rings obscure the target, and “M” to let the blocker body obscure the target; shadower is a string identifying what surfaces can shadow the target, formed by concatenating “P” to let the planet shadow the target, “R” to let the rings shadow the target, and “M” to let the blocker body shadow the target; and face is a string identifying which face(s) of the surface to include, where “D” includes only the day side of the target, “N” includes only the night side of the target, and “” includes both faces of the target.

• blocker – Optionally, the name of the body to use for any “M” codes that appear in the mask_desc.

• ignore_shadows – True to ignore any shadower or face constraints; default is False.

Returns:

Boolean bitmask containing the mask.

metadata_tools.geometry_support.formatting

circle_coverage(angles: Any, null_value: float | str, sampling: int, flag: str | None = None) → list[Any]

Return inferred angular coverage, accounting for the mask.

Parameters:

• angles – Angles in deg, as a list, np.array, or Scalar.

• null_value – Value to return when fully masked.

• sampling – Pixel sampling density.

• flag – “-180” to return values in the range (-180,180) rather than (0,360).

Returns:

Minimum and maximum values in the cyclic array.

formatted_column(values: Any, fmt: tuple[str, int, int, str, str | None, float | str, float, float, int, str], sampling: int) → str

Return one formatted column (or a pair of columns) as a string.

Parameters:

• values – A Scalar of values with its applied mask (or a string).

• fmt – Format tuple from FORMAT_DICT/ALT_FORMAT_DICT.

• sampling – Pixel sampling density.

Returns:

Formatted column.

metadata_tools.geometry_support.formats

ALT_FORMAT_DICT: dict[tuple[str, str], tuple[str, int, int, str, str | None, float | str, float, float, int, str]] = {('longitude', '-180'): ('-180', 2, 8, '%8.3f', None, -999.0, -180, 180, 0, ''), ('ring_angular_resolution', 'km'): ('KM', 2, 10, '%10.5f', '%10.4e', -999.0, 0, 0, 0, ''), ('ring_longitude', '-180'): ('-180', 2, 8, '%8.3f', None, -999.0, -180, 180, 0, ''), ('sub_longitude', '-180'): ('-180', 2, 8, '%8.3f', None, -999.0, -180, 180, 0, '')}

Alternate format entries keyed by (column_name, alt_format_tag).

FORMAT_DICT: dict[str, tuple[str, int, int, str, str | None, float | str, float, float, int, str]] = {'altitude': ('', 2, 12, '%12.3f', '%12.5e', -99999.0, 0, 0, 0, ''), 'ansa_altitude': ('', 2, 12, '%12.3f', '%12.5e', -9990000000.0, 0, 0, 0, ''), 'ansa_longitude': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'ansa_radial_resolution': ('', 2, 10, '%10.5f', '%10.4e', -999.0, 0, 0, 0, ''), 'ansa_radius': ('', 2, 12, '%12.3f', '%12.5e', -999.0, 0, 0, 0, ''), 'ansa_vertical_resolution': ('', 2, 10, '%10.5f', '%10.4e', -999.0, 0, 0, 0, ''), 'body_diameter_in_pixels': ('', 1, 12, '%12.3f', '%12.5e', -999.0, 0, 0, 0, ''), 'center_coordinate': ('', 1, 12, '%12.3f', '%12.5e', -99999, -10000, 10000, 1, 'null'), 'center_declination': ('DEG', 2, 10, '%10.6f', '%10.5f', -999.0, -90, 90, 0, ''), 'center_distance': ('', 2, 12, '%12.3f', '%12.5e', -999.0, 0, 0, 0, ''), 'center_emission_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 90, 0, ''), 'center_incidence_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 90, 0, ''), 'center_phase_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 180, 0, ''), 'center_resolution': ('', 2, 10, '%10.5f', '%10.4e', -999.0, 0, 0, 0, ''), 'center_right_ascension': ('360', 2, 10, '%10.6f', '%10.5f', -999.0, 0, 360, 0, ''), 'coarsest_resolution': ('', 2, 10, '%10.5f', '%10.4e', -999.0, 0, 0, 0, ''), 'declination': ('DEG', 2, 10, '%10.6f', '%10.5f', -999.0, -90, 90, 0, ''), 'distance': ('', 2, 12, '%12.3f', '%12.5e', -999.0, 0, 0, 0, ''), 'emission_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 90, 0, ''), 'event_time': ('ISO', 2, 25, '%25s', '%25s', '"NA"', 0, 0, 0, ''), 'finest_resolution': ('', 2, 10, '%10.5f', '%10.4e', -999.0, 0, 0, 0, ''), 'incidence_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 180, 0, ''), 'latitude': ('DEG', 2, 8, '%8.3f', None, -999.0, -90, 90, 0, ''), 'limb_altitude': ('', 2, 12, '%12.3f', '%12.5e', -99999.0, 0, 0, 0, ''), 'limb_clock_angle': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'longitude': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'phase_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 180, 0, ''), 'pole_clock_angle': ('DEG', 1, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'pole_position_angle': ('DEG', 1, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'radius_in_pixels': ('', 2, 12, '%12.3f', '%12.5e', -999.0, 0, 0, 0, ''), 'resolution': ('', 2, 10, '%10.5f', '%10.4e', -999.0, 0, 0, 0, ''), 'right_ascension': ('360', 2, 10, '%10.6f', '%10.5f', -999.0, 0, 360, 0, ''), 'ring_angular_resolution': ('DEG', 2, 10, '%10.5f', '%6.3e', -999.0, 0, 0, 0, ''), 'ring_azimuth': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'ring_center_emission_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 180, 0, ''), 'ring_center_incidence_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 180, 0, ''), 'ring_elevation': ('DEG', 2, 8, '%8.3f', None, -999.0, -90, 90, 0, ''), 'ring_emission_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 180, 0, ''), 'ring_incidence_angle': ('DEG', 2, 8, '%8.3f', None, -999.0, 0, 180, 0, ''), 'ring_longitude': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'ring_radial_resolution': ('', 2, 10, '%10.5f', '%10.4e', -999.0, 0, 0, 0, ''), 'ring_radius': ('', 2, 12, '%12.3f', '%12.5e', -999.0, 0, 0, 0, ''), 'ring_sub_observer_longitude': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'ring_sub_solar_longitude': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'sub_observer_latitude': ('DEG', 2, 8, '%8.3f', None, -999.0, -90, 90, 0, ''), 'sub_observer_longitude': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'sub_solar_latitude': ('DEG', 2, 8, '%8.3f', None, -999.0, -90, 90, 0, ''), 'sub_solar_longitude': ('360', 2, 8, '%8.3f', None, -999.0, 0, 360, 0, ''), 'where_antisunward': ('', 2, 1, '%1d', None, 0, 0, 0, 0, ''), 'where_in_back': ('', 2, 1, '%1d', None, 0, 0, 0, 0, ''), 'where_in_front': ('', 2, 1, '%1d', None, 0, 0, 0, 0, ''), 'where_inside_shadow': ('', 2, 1, '%1d', None, 0, 0, 0, 0, '')}

Maps each geometry column name to its ten-element format tuple of formatting, units, null value, valid range, and null-link metadata.

MISSION_TABLE: list[Any] = []

Host mission table with spacecraft-clock strings converted to ticks.

metadata_tools.geometry_support.bodies_select

get_primary(record: Record, table: list[Any], sclk: str) → tuple[str, list[str], list[str], list[str]]

Determine the primary for a given spacecraft clock count.

Uses the converted default bodies table, which contains sclk ticks instead of strings.

Parameters:

• record – The geometry record.

• table – Converted default bodies table containing sclk ticks instead of strings.

• sclk – Spacecraft clock string corresponding to the observation time.

Returns:

A tuple (primary, secondaries, selections, additions), where primary is the name of the primary corresponding to the given SCLK value, secondaries holds the names of any secondaries, selections holds the names of any selected bodies, and additions holds the names of any added bodies.

get_system(body: str) → str | None

Look up the system for a body.

Parameters:

body – Body for which to determine the system. For a satellite, the system is the parent. For a planet, the system is itself.

Returns:

Name of system, body, or None if the body is not registered.

inventory(record: Record, bodies: list[str] | dict[str, Any]) → list[str]

Obtain image inventory if possible.

Parameters:

• record – The geometry record.

• bodies – Bodies to test.

Returns:

List of inventory bodies.

obs_excluded(record: Record, exceptions: list[str]) → bool

Determine whether an observation is excluded.

Parameters:

• record – The geometry record.

• exceptions – List of regular expressions to test against the observation ID.

Returns:

True if the observation is excluded.

select_bodies(record: Record, bodies: dict[str, Any]) → list[str]

Select all bodies to include in this record.

The selection follows these rules:

1. The primary and secondary bodies are always included.

2. Children of the primary are included if they intersect the FOV. If there are selections, then only the selected children are considered.

3. If there is no primary, all selections that intersect the FOV are included.

4. The target is always included.

5. If the target is a satellite, the parent is included.

6. Additions are included whenever they intersect the FOV, regardless of the primary.

Parameters:

• record – The geometry record.

• bodies – All bodies.

Returns:

List of selected bodies.