Artifact I/O

Backend-neutral storage contracts for slide features, tissue, tiles, thumbnails, and retrieval representations.

Slide artifacts

class pathforge.core.io.slide_artifacts.base.FileHandleH5[source]

Bases: object

Context-managed HDF5 file wrapper used by PathForge artifact helpers.

path: Path
mode: str
property h5: File
__init__(path: Path, mode: str = 'a', _h5: File | None = None) → None
Parameters:

  • path (Path)

  • mode (str)

  • _h5 (File | None)

Return type:

None

pathforge.core.io.slide_artifacts.base.exists(h5_file: File, h5_path: str) → bool[source]

Return whether one HDF5 object path exists in the open file.

Parameters:

  • h5_file (File)

  • h5_path (str)

Return type:

bool

pathforge.core.io.slide_artifacts.base.get_dataset(h5_file: File, h5_path: str) → Dataset | None[source]

Return the dataset at h5_path or None when missing or not a dataset.

Parameters:

  • h5_file (File)

  • h5_path (str)

Return type:

Dataset | None

pathforge.core.io.slide_artifacts.base.get_status(h5_obj: Dataset | Group) → str | None[source]

Return the PathForge completion status attribute for one HDF5 object.

Parameters:

h5_obj (Dataset | Group)

Return type:

str | None

pathforge.core.io.slide_artifacts.base.is_complete(h5_obj: Dataset | Group) → bool[source]

Return whether one HDF5 object is marked as completely written.

Parameters:

h5_obj (Dataset | Group)

Return type:

bool

pathforge.core.io.slide_artifacts.base.delete_if_exists(h5_file: File, h5_path: str) → None[source]

Delete one HDF5 object path when it already exists.

Parameters:

  • h5_file (File)

  • h5_path (str)

Return type:

None

pathforge.core.io.slide_artifacts.base.ensure_group(h5_file: File, group_path: str) → Group[source]

Create or return one HDF5 group path.

Parameters:

  • h5_file (File)

  • group_path (str)

Return type:

Group

pathforge.core.io.slide_artifacts.base.write_json_dataset(h5_file: File, dataset_path: str, obj: Any) → None[source]

Write obj as a scalar UTF-8 JSON dataset (overwrite).

Parameters:

  • h5_file (File)

  • dataset_path (str)

  • obj (Any)

Return type:

None

pathforge.core.io.slide_artifacts.base.read_json_dataset(h5_file: File, dataset_path: str) → Any[source]

Read scalar UTF-8 JSON dataset.

Parameters:

  • h5_file (File)

  • dataset_path (str)

Return type:

Any

pathforge.core.io.slide_artifacts.base.write_array_dataset(h5_file: File, dataset_path: str, array: ndarray, *, dtype: Any, compression: str | None = 'gzip', compression_opts: int = 4) → None[source]

Write array dataset (overwrite), including UTF-8 string arrays.

Parameters:

  • h5_file (File)

  • dataset_path (str)

  • array (ndarray)

  • dtype (Any)

  • compression (str | None)

  • compression_opts (int)

Return type:

None

pathforge.core.io.slide_artifacts.base.read_array_dataset(h5_file: File, dataset_path: str) → ndarray[source]

Read one HDF5 array dataset into a NumPy array.

Parameters:

  • h5_file (File)

  • dataset_path (str)

Return type:

ndarray

pathforge.core.io.slide_artifacts.atomic.validate_h5_artifact(path: str | Path) → None[source]

Open and traverse one HDF5 artifact to ensure it is structurally readable.

Parameters:

path (str | Path)

Return type:

None

pathforge.core.io.slide_artifacts.atomic.quarantine_corrupt_artifact(artifact_path: str | Path, *, reason: Exception | None = None) → Path[source]

Move a corrupt artifact aside into _corrupt and return the new path.

Parameters:

  • artifact_path (str | Path)

  • reason (Exception | None)

Return type:

Path

pathforge.core.io.slide_artifacts.atomic.ensure_artifact_readable_or_quarantine(artifact_path: str | Path) → bool[source]

Validate one artifact in-place, quarantining it when it is unreadable.

Parameters:

artifact_path (str | Path)

Return type:

bool

pathforge.core.io.slide_artifacts.atomic.atomic_slide_artifact_write(artifact_path: str | Path, *, validate: Callable[[FileHandleH5], None] | None = None) → Iterator[FileHandleH5][source]

Write one slide artifact atomically via a temporary HDF5 file.

Parameters:

  • artifact_path (str | Path)

  • validate (Callable[[FileHandleH5], None] | None)

Return type:

Iterator[FileHandleH5]

class pathforge.core.io.slide_artifacts.layout.H5Layout[source]

Bases: object

Build canonical dataset paths inside a slide-artifact H5 file.

Slide-level tissue and thumbnail data live under annotations/ and thumbnail/. Each tiling configuration lives under bags/{bag_id} with coordinates, tiling metadata, an optional overview, and feature matrices keyed by extractor name.

tissue_dataset: str
thumbnail_group: str
thumbnail_image_name: str
thumbnail_spec_name: str
bags_group: str
coords_name: str
tiling_spec_name: str
tiles_overview_name: str
features_group_name: str
bag_group(bag_id: str) → str[source]

Return the root group for one tiling configuration: bags/{bag_id}.

Parameters:

bag_id (str)

Return type:

str

coords_dataset(bag_id: str) → str[source]

Return the coords dataset for one bag.

Parameters:

bag_id (str)

Return type:

str

thumbnail_image_dataset() → str[source]

Return the slide-level thumbnail image dataset.

Return type:

str

thumbnail_spec_dataset() → str[source]

Return the slide-level thumbnail spec dataset.

Return type:

str

tiling_spec_dataset(bag_id: str) → str[source]

Return the tiling-spec dataset for one bag.

Parameters:

bag_id (str)

Return type:

str

tiles_overview_dataset(bag_id: str) → str[source]

Return the tiles-overview dataset for one bag.

Parameters:

bag_id (str)

Return type:

str

features_group(bag_id: str) → str[source]

Return the features group for one bag.

Parameters:

bag_id (str)

Return type:

str

features_dataset(bag_id: str, extractor_name: str) → str[source]

Return one feature dataset under features/{extractor_name}.

Parameters:

  • bag_id (str)

  • extractor_name (str)

Return type:

str

__init__(tissue_dataset: str = 'annotations/tissue', thumbnail_group: str = 'thumbnail', thumbnail_image_name: str = 'image', thumbnail_spec_name: str = 'spec', bags_group: str = 'bags', coords_name: str = 'coords', tiling_spec_name: str = 'tiling_spec', tiles_overview_name: str = 'tiles_overview', features_group_name: str = 'features') → None
Parameters:

  • tissue_dataset (str)

  • thumbnail_group (str)

  • thumbnail_image_name (str)

  • thumbnail_spec_name (str)

  • bags_group (str)

  • coords_name (str)

  • tiling_spec_name (str)

  • tiles_overview_name (str)

  • features_group_name (str)

Return type:

None

pathforge.core.io.slide_artifacts.features.features_exist(slide_artifact: FileHandleH5, bag_id: str, extractor_name: str, *, expected_rows: int | None = None, layout: H5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether a complete feature matrix exists for one bag/extractor pair.

Parameters:

  • slide_artifact (FileHandleH5)

  • bag_id (str)

  • extractor_name (str)

  • expected_rows (int | None)

  • layout (H5Layout)

Return type:

bool

pathforge.core.io.slide_artifacts.features.read_features(slide_artifact: FileHandleH5, bag_id: str, extractor_name: str, *, layout: H5Layout = DEFAULT_LAYOUT) → ndarray[source]

Read a feature matrix shaped [N, D] as float32.

Parameters:
Return type:

ndarray

pathforge.core.io.slide_artifacts.features.infer_feature_level(slide_artifact: FileHandleH5, bag_id: str, extractor_name: str, *, layout: H5Layout = DEFAULT_LAYOUT) → str[source]

Infer feature level for one slide artifact.

Returns:

  • “patch”

  • ”slide”

  • ”unknown”

  • ”invalid”

Parameters:
Return type:

str

pathforge.core.io.slide_artifacts.features.write_features(slide_artifact: FileHandleH5, bag_id: str, extractor_name: str, feature_matrix: ndarray, *, layout: H5Layout = DEFAULT_LAYOUT) → None[source]

Write a feature matrix shaped [N, D] as float32.

Parameters:

  • slide_artifact (FileHandleH5)

  • bag_id (str)

  • extractor_name (str)

  • feature_matrix (ndarray)

  • layout (H5Layout)

Return type:

None

pathforge.core.io.slide_artifacts.features.delete_all_features_for_bag(slide_artifact: FileHandleH5, bag_id: str, *, layout: H5Layout = DEFAULT_LAYOUT) → None[source]

Delete the full features group for one bag when it exists.

Parameters:
Return type:

None

pathforge.core.io.slide_artifacts.tiles.coords_exist(slide_artifact: FileHandleH5, bag_id: str, *, layout: H5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether a complete coordinate matrix exists for bag_id.

Parameters:
Return type:

bool

pathforge.core.io.slide_artifacts.tiles.read_coords(slide_artifact: FileHandleH5, bag_id: str, *, layout: H5Layout = DEFAULT_LAYOUT) → ndarray[source]

Read bag tile coordinates as an int32 matrix shaped [N, 5].

Parameters:
Return type:

ndarray

pathforge.core.io.slide_artifacts.tiles.write_coords(slide_artifact: FileHandleH5, bag_id: str, coords: ndarray, *, layout: H5Layout = DEFAULT_LAYOUT) → None[source]

Write bag tile coordinates shaped [N, 5] as int32.

Parameters:
Return type:

None

pathforge.core.io.slide_artifacts.tiles.coords_num_rows(slide_artifact: FileHandleH5, bag_id: str, *, layout: H5Layout = DEFAULT_LAYOUT) → int[source]

Return number of coord rows for a bag without loading the entire dataset. If coords don’t exist yet, returns 0.

Parameters:
Return type:

int

pathforge.core.io.slide_artifacts.tiles.tiling_spec_exists(slide_artifact: FileHandleH5, bag_id: str, *, layout: H5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether a complete tiling-spec JSON object exists for bag_id.

Parameters:
Return type:

bool

pathforge.core.io.slide_artifacts.tiles.read_tiling_spec(slide_artifact: FileHandleH5, bag_id: str, *, layout: H5Layout = DEFAULT_LAYOUT) → dict[str, Any][source]

Read the stored tiling-spec JSON object for one bag.

Parameters:
Return type:

dict[str, Any]

pathforge.core.io.slide_artifacts.tiles.write_tiling_spec(slide_artifact: FileHandleH5, bag_id: str, tiling_spec: dict[str, Any], *, layout: H5Layout = DEFAULT_LAYOUT) → None[source]

Write the tiling-spec JSON object for one bag.

Parameters:
Return type:

None

pathforge.core.io.slide_artifacts.tiles.tiling_spec_matches(slide_artifact: FileHandleH5, bag_id: str, expected_tiling_spec: dict[str, Any], *, layout: H5Layout = DEFAULT_LAYOUT, float_tol: float = 1e-6) → bool[source]

Check whether stored tiling_spec matches the expected one for the provided keys.

  • Subset match: only keys in expected_tiling_spec are checked.

  • Numeric normalization:

    • tile_px / stride_px compared as ints

    • tile_mpp compared with tolerance

Parameters:

  • slide_artifact (FileHandleH5)

  • bag_id (str)

  • expected_tiling_spec (dict[str, Any])

  • layout (H5Layout)

  • float_tol (float)

Return type:

bool

pathforge.core.io.slide_artifacts.tiles.tiles_overview_exists(slide_artifact: FileHandleH5, bag_id: str, *, layout: H5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether a complete serialized tiles-overview image exists for one bag.

Parameters:
Return type:

bool

pathforge.core.io.slide_artifacts.tiles.write_tiles_overview(slide_artifact: FileHandleH5, bag_id: str, image_bytes: bytes, *, layout: H5Layout = DEFAULT_LAYOUT) → None[source]

Store compressed image bytes (e.g. JPEG) for the bag tiles overview.

Stored as a 1D uint8 array for robust binary storage in HDF5. Existing dataset is overwritten by write_array_dataset.

Parameters:
Return type:

None

pathforge.core.io.slide_artifacts.tiles.read_tiles_overview(slide_artifact: FileHandleH5, bag_id: str, *, layout: H5Layout = DEFAULT_LAYOUT) → bytes[source]

Read the serialized tiles-overview image bytes for one bag.

Parameters:
Return type:

bytes

pathforge.core.io.slide_artifacts.tissue.tissue_exists(slide_artifact: FileHandleH5, *, layout: H5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether a complete tissue-annotation payload exists in the slide artifact.

Parameters:
Return type:

bool

pathforge.core.io.slide_artifacts.tissue.read_tissue(slide_artifact: FileHandleH5, *, layout: H5Layout = DEFAULT_LAYOUT) → list[list[list[list[float]]]][source]

Read tissue polygons from H5.

Returns:

Nested polygons, each containing an outer ring and optional hole rings.

Parameters:
Return type:

list[list[list[list[float]]]]

pathforge.core.io.slide_artifacts.tissue.write_tissue(slide_artifact: FileHandleH5, tissue_polygons: Any, *, layout: H5Layout = DEFAULT_LAYOUT) → None[source]

Write tissue polygons to H5 as JSON using the internal nested-rings contract.

Parameters:

  • slide_artifact (FileHandleH5) – Open target slide artifact.

  • tissue_polygons (Any) – Nested polygons containing outer and optional hole rings.

  • layout (H5Layout) – Dataset layout used to locate the tissue payload.

Return type:

None

pathforge.core.io.slide_artifacts.tissue.register_external_tissue_loader(*suffixes: str) → Callable[[Callable[[Path], list[list[list[list[float]]]]]], Callable[[Path], list[list[list[list[float]]]]]][source]

Decorator to register an external tissue loader for one or more suffixes.

Parameters:

suffixes (str)

Return type:

Callable[[Callable[[Path], list[list[list[list[float]]]]]], Callable[[Path], list[list[list[list[float]]]]]]

pathforge.core.io.slide_artifacts.tissue.load_external_tissue_polygons(path: str | Path) → list[list[list[list[float]]]][source]

Load tissue polygons from an external file (currently supports .geojson).

Returns:

TissuePolygons using the internal nested-rings contract.

Parameters:

path (str | Path)

Return type:

list[list[list[list[float]]]]

pathforge.core.io.slide_artifacts.thumbnail.thumbnail_image_exists(slide_artifact: FileHandleH5, *, layout: H5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether the slide-level thumbnail image dataset is present.

Parameters:
Return type:

bool

pathforge.core.io.slide_artifacts.thumbnail.write_thumbnail_image(slide_artifact: FileHandleH5, image_bytes: bytes, *, layout: H5Layout = DEFAULT_LAYOUT) → None[source]

Store one encoded slide thumbnail as a 1D uint8 dataset.

Parameters:
Return type:

None

pathforge.core.io.slide_artifacts.thumbnail.read_thumbnail_image(slide_artifact: FileHandleH5, *, layout: H5Layout = DEFAULT_LAYOUT) → bytes[source]

Read the encoded slide thumbnail bytes.

Parameters:
Return type:

bytes

pathforge.core.io.slide_artifacts.thumbnail.thumbnail_spec_exists(slide_artifact: FileHandleH5, *, layout: H5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether the slide-level thumbnail spec dataset is present.

Parameters:
Return type:

bool

pathforge.core.io.slide_artifacts.thumbnail.write_thumbnail_spec(slide_artifact: FileHandleH5, thumbnail_spec: dict[str, Any], *, layout: H5Layout = DEFAULT_LAYOUT) → None[source]

Write one JSON thumbnail spec for slide-level thumbnail interpretation.

Parameters:
Return type:

None

pathforge.core.io.slide_artifacts.thumbnail.read_thumbnail_spec(slide_artifact: FileHandleH5, *, layout: H5Layout = DEFAULT_LAYOUT) → dict[str, Any][source]

Read the JSON thumbnail spec.

Parameters:
Return type:

dict[str, Any]

Retrieval artifacts

pathforge.core.io.slide_retrieval.descriptors.descriptor_exists(retrieval_artifact: FileHandleH5, tile_id: str, descriptor_name: str, *, expected_rows: int | None = None, expected_dim: int | None = None, expected_metadata: dict[str, Any] | None = None, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether one descriptor matches its expected cache contract.

Inputs:

expected_rows: Optional expected row count for the (N, D) matrix. expected_dim: Optional expected descriptor width. expected_metadata: Optional HDF5 attribute values required for reuse.

Output:

True only when the dataset exists and every supplied constraint matches.

Example

descriptor_exists(h5, "256px_0.5mpp", "mean_rgb", expected_rows=20).

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • descriptor_name (str)

  • expected_rows (int | None)

  • expected_dim (int | None)

  • expected_metadata (dict[str, Any] | None)

  • layout (RetrievalH5Layout)

Return type:

bool

pathforge.core.io.slide_retrieval.descriptors.read_descriptor(retrieval_artifact: FileHandleH5, tile_id: str, descriptor_name: str, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → ndarray[source]

Read one retrieval-side descriptor matrix.

Parameters:
Return type:

ndarray

pathforge.core.io.slide_retrieval.descriptors.write_descriptor(retrieval_artifact: FileHandleH5, tile_id: str, descriptor_name: str, descriptor_matrix: ndarray, *, metadata: dict[str, Any] | None = None, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Write one retrieval-side descriptor matrix.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • descriptor_name (str)

  • descriptor_matrix (ndarray)

  • metadata (dict[str, Any] | None)

  • layout (RetrievalH5Layout)

Return type:

None

class pathforge.core.io.slide_retrieval.layout.RetrievalH5Layout[source]

Bases: object

Build canonical dataset paths inside a retrieval-artifact H5 file.

Per-tiling descriptors and representations live below bags/{tile_id}. Slide representations are stored directly below their representation ID; multi-slide aggregations add an entry ID for the concrete member set.

retrieval_representations_group_name: str
descriptors_group_name: str
retrieval_representation_type_name: str
retrieval_representation_metadata_name: str
retrieval_representation_params_name: str
retrieval_representation_embedding_name: str
retrieval_representation_additional_data_group_name: str
tile_group(tile_id: str) → str[source]

Return the root group for one tiling configuration: bags/{tile_id}.

Parameters:

tile_id (str)

Return type:

str

retrieval_representations_group(tile_id: str) → str[source]

Return the retrieval-representation container under one tile group.

Parameters:

tile_id (str)

Return type:

str

descriptors_group(tile_id: str) → str[source]

Return the retrieval-side descriptor cache group under one tile group.

Parameters:

tile_id (str)

Return type:

str

descriptor(tile_id: str, descriptor_name: str) → str[source]

Return one descriptor dataset: bags/{tile_id}/descriptors/{descriptor_name}.

Parameters:

  • tile_id (str)

  • descriptor_name (str)

Return type:

str

retrieval_representation_group(tile_id: str, representation_id: str) → str[source]

Return the group for one retrieval configuration under one tile group.

Parameters:

  • tile_id (str)

  • representation_id (str)

Return type:

str

retrieval_representation_entry_group(tile_id: str, representation_id: str, entry_id: str | None) → str[source]

Return the group for one stored retrieval entry under one representation.

When entry_id is None, the representation root itself is used.

Parameters:

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

Return type:

str

retrieval_representation_metadata(tile_id: str, representation_id: str, entry_id: str | None) → str[source]

Return the JSON metadata dataset for one retrieval entry.

Parameters:

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

Return type:

str

retrieval_representation_type(tile_id: str, representation_id: str, entry_id: str | None) → str[source]

Return the representation-type dataset for one retrieval entry.

Parameters:

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

Return type:

str

retrieval_representation_params(tile_id: str, representation_id: str, entry_id: str | None) → str[source]

Return the readable params dataset for one retrieval entry.

Parameters:

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

Return type:

str

retrieval_representation_embedding(tile_id: str, representation_id: str, entry_id: str | None) → str[source]

Return the main embedding dataset for one retrieval entry.

Parameters:

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

Return type:

str

retrieval_representation_additional_data_group(tile_id: str, representation_id: str, entry_id: str | None) → str[source]

Return the group that stores extra strategy-specific arrays.

Parameters:

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

Return type:

str

retrieval_representation_additional_data(tile_id: str, representation_id: str, entry_id: str | None, name: str) → str[source]

Return one dataset inside additional_data/ for a retrieval entry.

Parameters:

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • name (str)

Return type:

str

__init__(retrieval_representations_group_name: str = 'retrieval_representations', descriptors_group_name: str = 'descriptors', retrieval_representation_type_name: str = 'representation_type', retrieval_representation_metadata_name: str = 'metadata', retrieval_representation_params_name: str = 'params', retrieval_representation_embedding_name: str = 'embedding', retrieval_representation_additional_data_group_name: str = 'additional_data') → None
Parameters:

  • retrieval_representations_group_name (str)

  • descriptors_group_name (str)

  • retrieval_representation_type_name (str)

  • retrieval_representation_metadata_name (str)

  • retrieval_representation_params_name (str)

  • retrieval_representation_embedding_name (str)

  • retrieval_representation_additional_data_group_name (str)

Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.retrieval_representation_entry_exists(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether one retrieval entry contains the required stored objects.

Parameters:
Return type:

bool

pathforge.core.io.slide_retrieval.retrieval_representations.read_retrieval_representation_entry(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → dict[str, Any][source]

Read all stored objects for one retrieval entry.

Parameters:
Return type:

dict[str, Any]

pathforge.core.io.slide_retrieval.retrieval_representations.write_retrieval_representation_entry(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, metadata: dict[str, Any], embedding: ndarray, params: dict[str, Any] | None = None, additional_data: dict[str, ndarray] | None = None, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Write all stored objects for one retrieval entry.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • metadata (dict[str, Any])

  • embedding (ndarray)

  • params (dict[str, Any] | None)

  • additional_data (dict[str, ndarray] | None)

  • layout (RetrievalH5Layout)

Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.retrieval_representation_exists(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, expected_shape: tuple[int, ...] | None = None, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether the main embedding exists for one retrieval entry.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • expected_shape (tuple[int, ...] | None)

  • layout (RetrievalH5Layout)

Return type:

bool

pathforge.core.io.slide_retrieval.retrieval_representations.retrieval_representation_item_exists(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → bool[source]

Backward-compatible alias for the full-entry existence check.

Parameters:
Return type:

bool

pathforge.core.io.slide_retrieval.retrieval_representations.read_retrieval_representation(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → ndarray[source]

Read the main embedding array for one retrieval entry.

Parameters:
Return type:

ndarray

pathforge.core.io.slide_retrieval.retrieval_representations.write_retrieval_representation(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, data: ndarray, *, dtype: dtype | str | None = None, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Write the main embedding array for one retrieval entry.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • data (ndarray)

  • dtype (dtype | str | None)

  • layout (RetrievalH5Layout)

Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.read_retrieval_representation_type(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → str[source]

Read the representation-type label for one retrieval entry.

Parameters:
Return type:

str

pathforge.core.io.slide_retrieval.retrieval_representations.write_retrieval_representation_type(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, representation_type: str, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Write the representation-type label for one retrieval entry.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • representation_type (str)

  • layout (RetrievalH5Layout)

Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.read_retrieval_representation_metadata(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → dict[str, Any][source]

Read the metadata payload for one retrieval entry.

Parameters:
Return type:

dict[str, Any]

pathforge.core.io.slide_retrieval.retrieval_representations.write_retrieval_representation_metadata(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, metadata: dict[str, Any], *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Write the metadata payload for one retrieval entry.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • metadata (dict[str, Any])

  • layout (RetrievalH5Layout)

Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.read_retrieval_representation_params(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → dict[str, Any][source]

Read the readable params payload for one retrieval entry.

Parameters:
Return type:

dict[str, Any]

pathforge.core.io.slide_retrieval.retrieval_representations.write_retrieval_representation_params(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, params: dict[str, Any], *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Write the readable params payload for one retrieval entry.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • params (dict[str, Any])

  • layout (RetrievalH5Layout)

Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.additional_retrieval_representation_data_exists(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, name: str, *, expected_shape: tuple[int, ...] | None = None, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → bool[source]

Return whether one additional-data array exists for a retrieval entry.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • name (str)

  • expected_shape (tuple[int, ...] | None)

  • layout (RetrievalH5Layout)

Return type:

bool

pathforge.core.io.slide_retrieval.retrieval_representations.read_additional_retrieval_representation_data(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, name: str, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → ndarray[source]

Read one additional-data array for a retrieval entry.

Parameters:
Return type:

ndarray

pathforge.core.io.slide_retrieval.retrieval_representations.write_additional_retrieval_representation_data(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, name: str, data: ndarray, *, dtype: dtype | str | None = None, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Write one additional-data array for a retrieval entry.

Parameters:

  • retrieval_artifact (FileHandleH5)

  • tile_id (str)

  • representation_id (str)

  • entry_id (str | None)

  • name (str)

  • data (ndarray)

  • dtype (dtype | str | None)

  • layout (RetrievalH5Layout)

Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.delete_retrieval_representation(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, entry_id: str | None, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Delete one retrieval entry group and all stored objects under it.

Parameters:
Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.delete_all_retrieval_representations_for_representation(retrieval_artifact: FileHandleH5, tile_id: str, representation_id: str, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Delete all entry groups for one retrieval configuration.

Parameters:
Return type:

None

pathforge.core.io.slide_retrieval.retrieval_representations.delete_all_retrieval_representations_for_bag(retrieval_artifact: FileHandleH5, tile_id: str, *, layout: RetrievalH5Layout = DEFAULT_LAYOUT) → None[source]

Delete all retrieval representations stored under one tile group.

Parameters:
Return type:

None