radioviz.services.tiff_metadata

TIFF metadata utilities for RadioViz.

This module provides helper functions to extract, normalize, and prepare TIFF metadata for persistence and display. It focuses on the subset of TIFF tags that are meaningful for autoradiography images and ensures values are kept JSON- and HDF5-friendly for workspace serialization.

Module Attributes

TIFF_TAGS_TO_PRESERVE

Mapping of TIFF tag IDs to their canonical names for preserved metadata.

Functions

`build_tiff_extratags`(metadata, ...)	Build TIFF extratags for writing derived images.
`build_tiff_kwargs`(metadata, derivation_note, ...)	Build standard TIFF keyword arguments for writing metadata.
`derive_tiff_metadata`(parent_metadata, ...)	Derive TIFF metadata for a child image.
`extract_tiff_metadata`(raw_bytes)	Extract preserved TIFF metadata from raw TIFF bytes.
`extract_xyz_dat_metadata`(dat_path[, image_shape])	Extract TIFF-style metadata from a XYZ DAT sidecar file.
`metadata_entries`(metadata)	Build displayable metadata entries from a metadata dictionary.
`pixel_size_from_metadata`(metadata)	Compute the pixel size in meters from TIFF metadata.

radioviz.services.tiff_metadata._append_description(existing: str, note: str) → str[source]

Append a derivation note to an existing description string.

Parameters:

existing (str) – Existing description string.
note (str) – Derivation note to append.

Returns:

Updated description string.

Return type:

str

radioviz.services.tiff_metadata._append_software(existing: str, suffix: str) → str[source]

Append a software suffix if not already present.

Parameters:

existing (str) – Existing software string.
suffix (str) – Software suffix to append.

Returns:

Updated software string.

Return type:

str

radioviz.services.tiff_metadata._apply_description_and_software(tag_map: dict[int, Any], derivation_note: str | None, software_suffix: str) → dict[int, Any][source]

Apply derivation note and software suffix to tag values.

Parameters:

tag_map (dict[int, Any]) – Tag map to update.
derivation_note (str | None) – Description of the derivation to append.
software_suffix (str) – Software string to append if missing.

Returns:

Updated tag map.

Return type:

dict[int, Any]

radioviz.services.tiff_metadata._ascii_safe(value: str) → str[source]

Normalize a string to 7-bit ASCII for TIFF string tags.

Parameters:: value (str) – Input string to normalize.
Returns:: ASCII-safe string with non-ASCII characters replaced.
Return type:: str

radioviz.services.tiff_metadata._build_dat_description(sections: dict[str, dict[str, str]]) → str | None[source]

Build an AIDA-style ImageDescription from DAT sections.

Parameters:: sections (dict[str, dict[str, str]]) – Parsed DAT sections.
Returns:: Description string or None.
Return type:: str | None

radioviz.services.tiff_metadata._coerce_float(value: Any) → float | None[source]

Coerce a value to float when possible.

Parameters:: value (Any) – Input value.
Returns:: Parsed float or None.
Return type:: float | None

radioviz.services.tiff_metadata._coerce_int(value: Any) → int | None[source]

Coerce a value to int when possible.

Parameters:: value (Any) – Input value.
Returns:: Parsed integer or None.
Return type:: int | None

radioviz.services.tiff_metadata._coerce_rational(value: Any) → tuple[int, int][source]

Coerce a value to a TIFF rational tuple.

A TIFF rational is a pair of 32-bit unsigned integers representing a fraction (numerator/denominator). TIFF uses this format to store resolution values and other floating-point quantities with high precision. For example, a resolution of 300 DPI is stored as the rational (300, 1), while 72.5 DPI would be stored as (145, 2).

This function accepts various input types and converts them to the rational tuple format expected by TIFF tags:

Fraction objects: extracts numerator and denominator directly
2-element lists/tuples: treats as (numerator, denominator)
Numeric types (int, float, numpy.number): converts to a reduced fraction

Parameters:: value (Any) – Value to coerce. Can be a Fraction, 2-element sequence, or any numeric type.
Returns:: Rational tuple (numerator, denominator).
Return type:: tuple[int, int]

Example:

>>> _coerce_rational(72.5)
(145, 2)
>>> _coerce_rational(Fraction(3, 4))
(3, 4)
>>> _coerce_rational([300, 1])
(300, 1)

radioviz.services.tiff_metadata._coerce_short(value: Any) → int[source]

Coerce a value to a TIFF short integer.

Parameters:: value (Any) – Value to coerce.
Returns:: Integer suitable for TIFF short tags.
Return type:: int

radioviz.services.tiff_metadata._decode_text_bytes(raw: bytes) → str[source]

Decode raw bytes preferring UTF-8, falling back to Latin-1.

Parameters:: raw (bytes) – Raw byte sequence.
Returns:: Decoded string.
Return type:: str

radioviz.services.tiff_metadata._find_dat_value(sections: dict[str, dict[str, str]], section_names: Iterable[str], key_names: Iterable[str]) → str | None[source]

Find the first matching value in DAT sections.

Parameters:

sections (dict[str, dict[str, str]]) – Parsed DAT sections.
section_names (Iterable[str]) – Section names to search.
key_names (Iterable[str]) – Key names to search.

Returns:

The first matching value, if any.

Return type:

str | None

radioviz.services.tiff_metadata._format_value(value: Any) → str[source]

Format a metadata value for display.

Parameters:: value (Any) – Metadata value to format.
Returns:: String representation of the value.
Return type:: str

radioviz.services.tiff_metadata._format_yes_no(value: Any) → str[source]

Format a boolean-like DAT value as yes/no.

Parameters:: value (Any) – DAT value to interpret.
Returns:: ‘yes’ or ‘no’.
Return type:: str

radioviz.services.tiff_metadata._map_photometric(value: str | None) → int[source]

Map photometric interpretation names to TIFF codes.

Parameters:: value (str | None) – Photometric interpretation string.
Returns:: TIFF photometric interpretation code.
Return type:: int

radioviz.services.tiff_metadata._metadata_from_tag_map(tag_map: dict[int, Any]) → dict[str, Any][source]

Convert a tag mapping into the metadata structure.

Parameters:: tag_map (dict[int, Any]) – Mapping of TIFF tag IDs to values.
Returns:: Metadata dictionary.
Return type:: dict[str, Any]

radioviz.services.tiff_metadata._normalize_tag_value(value: Any) → Any[source]

Normalize tag values to JSON- and HDF5-friendly types.

Parameters:: value (Any) – Tag value to normalize.
Returns:: Normalized tag value.
Return type:: Any

radioviz.services.tiff_metadata._parse_dat_sections(text: str) → dict[str, dict[str, str]][source]

Parse a DAT sidecar file into sectioned key/value pairs.

Parameters:: text (str) – Raw DAT file content.
Returns:: Mapping of section name to key/value pairs.
Return type:: dict[str, dict[str, str]]

radioviz.services.tiff_metadata._read_dat_text(dat_path: Path) → str[source]

Read DAT file text with a tolerant encoding fallback.

Parameters:: dat_path (Path) – Path to the DAT file.
Returns:: Decoded DAT text.
Return type:: str

radioviz.services.tiff_metadata._resolution_from_nm(pixel_size_nm: float | None) → float | None[source]

Convert a pixel size in nanometers to pixels per centimeter.

Parameters:: pixel_size_nm (float | None) – Pixel size in nanometers.
Returns:: Resolution in pixels per centimeter.
Return type:: float | None

radioviz.services.tiff_metadata._resolution_unit_to_meters(unit_value: int) → float | None[source]

Convert a TIFF ResolutionUnit to meters.

Parameters:: unit_value (int) – TIFF resolution unit code.
Returns:: Unit length in meters, or None if unsupported.
Return type:: float | None

radioviz.services.tiff_metadata._resolution_value(value: Any) → float | None[source]

Convert a TIFF resolution tag value to a floating-point number.

Parameters:: value (Any) – TIFF tag value.
Returns:: Resolution as float or None when unavailable.
Return type:: float | None

radioviz.services.tiff_metadata._sorted_tag_ids(keys: Any) → list[str][source]

Sort tag identifiers numerically when possible.

Parameters:: keys (Any) – Iterable of tag identifiers.
Returns:: Sorted list of tag identifiers as strings.
Return type:: list[str]

radioviz.services.tiff_metadata._tag_map_from_metadata(metadata: dict[str, Any]) → dict[int, Any][source]

Extract a tag-id to value mapping from metadata.

Parameters:: metadata (dict[str, Any]) – Metadata dictionary.
Returns:: Mapping of TIFF tag IDs to values.
Return type:: dict[int, Any]

radioviz.services.tiff_metadata.build_tiff_extratags(metadata: dict[str, Any], derivation_note: str | None, software_suffix: str) → list[tuple[int, str, int, Any, bool]][source]

Build TIFF extratags for writing derived images.

Parameters:

metadata (dict[str, Any]) – Image metadata dictionary.
derivation_note (str | None) – Description of the derivation to append.
software_suffix (str) – Software string to append if missing.

Returns:

List of TIFF extratag tuples.

Return type:

list[tuple[int, str, int, Any, bool]]

radioviz.services.tiff_metadata.build_tiff_kwargs(metadata: dict[str, Any], derivation_note: str | None, software_suffix: str) → dict[str, Any][source]

Build standard TIFF keyword arguments for writing metadata.

Parameters:

metadata (dict[str, Any]) – Image metadata dictionary.
derivation_note (str | None) – Description of the derivation to append.
software_suffix (str) – Software string to append if missing.

Returns:

Dictionary of tifffile.imwrite keyword arguments.

Return type:

dict[str, Any]

radioviz.services.tiff_metadata.derive_tiff_metadata(parent_metadata: dict[str, Any], derivation_note: str | None, software_suffix: str) → dict[str, Any][source]

Derive TIFF metadata for a child image.

Preserves only the configured TIFF tags, appends the derivation note to the ImageDescription tag (270), and ensures the Software tag (305) includes the provided suffix.

Parameters:

parent_metadata (dict[str, Any]) – Metadata from the parent image controller.
derivation_note (str | None) – Description of the derivation to append.
software_suffix (str) – Software string to append if missing.

Returns:

Derived metadata dictionary.

Return type:

dict[str, Any]

radioviz.services.tiff_metadata.extract_tiff_metadata(raw_bytes: bytes) → dict[str, Any][source]

Extract preserved TIFF metadata from raw TIFF bytes.

Parameters:: raw_bytes (bytes) – Raw TIFF file bytes.
Returns:: Metadata dictionary suitable for workspace serialization.
Return type:: dict[str, Any]

radioviz.services.tiff_metadata.extract_xyz_dat_metadata(dat_path: Path, image_shape: tuple[int, int] | None = None) → tuple[dict[str, Any], list[str]][source]

Extract TIFF-style metadata from a XYZ DAT sidecar file.

The DAT format is a sectioned key/value text file (INI-like). This function parses the DAT content and maps a subset of fields to TIFF tags used by RadioViz for metadata preservation.

Parameters:

dat_path (Path) – Path to the DAT sidecar file.
image_shape (tuple[int, int] | None) – Optional image shape (height, width) used as fallback for size tags.

Returns:

Metadata dictionary and list of warnings.

Return type:

tuple[dict[str, Any], list[str]]

radioviz.services.tiff_metadata.metadata_entries(metadata: dict[str, Any]) → list[tuple[str, str, str]][source]

Build displayable metadata entries from a metadata dictionary.

Parameters:: metadata (dict[str, Any]) – Metadata dictionary.
Returns:: List of (tag, name, value) tuples for display.
Return type:: list[tuple[str, str, str]]

radioviz.services.tiff_metadata.pixel_size_from_metadata(metadata: dict[str, Any]) → tuple[float, float] | None[source]

Compute the pixel size in meters from TIFF metadata.

The pixel size is derived from XResolution/YResolution and ResolutionUnit when available. ResolutionUnit values follow the TIFF specification:

2: inches
3: centimeters

Parameters:: metadata (dict[str, Any]) – Metadata dictionary containing TIFF tags.
Returns:: Tuple of (pixel_size_x_m, pixel_size_y_m) in meters, or None.
Return type:: tuple[float, float] | None

radioviz.services.tiff_metadata.TIFF_TAGS_TO_PRESERVE: dict[int, str] = {256: 'ImageWidth', 257: 'ImageLength', 258: 'BitsPerSample', 259: 'Compression', 262: 'PhotometricInterpretation', 270: 'ImageDescription', 271: 'Make', 282: 'XResolution', 283: 'YResolution', 296: 'ResolutionUnit', 305: 'Software'}: Mapping of TIFF tag IDs to their canonical names for preserved metadata.