SR-Forge

Patching

CrossPlatformFileLock

Cross-platform, multi-process lock implemented via atomic directory creation. Re-entrant within the same process (prevents Windows 'Resource deadlock avoided' issues).

Usage

lock_path = cache_dir / f"entry_{entry_idx}.lock" with CrossPlatformFileLock(lock_path): ...

Internally creates a directory: .lockdir

Patch dataclass

Represents a patch of an entry in the dataset. Each patch is defined by its entry index, patch index, and coordinates for each field. Variables: - entry_index: Index of the original entry in the dataset. - patch_index: Index of the patch within the entry. - coords: Dictionary mapping field names (e.g. 'lrs', 'hr') to patch coordinates as (y0, x0, h, w).

PatchedDataset

Bases: Dataset

A dataset wrapper that splits entries into non-overlapping spatial patches.

Wraps an existing dataset and divides each entry's spatial fields into a grid of patches. The patch grid is computed once at init (either from the first entry if same_shapes is True, or per-entry otherwise).

Grid computation needs only the shapes of each entry's fields, not the data. With shape_trace=True (default), shapes are obtained via :meth:~srforge.dataset.Dataset.meta_item — image-header reads plus a meta-tensor trace of the inner dataset's transform pipeline (see :mod:srforge.utils.shape_trace) — instead of loading every entry. Entries whose shapes can't be traced fall back to a real load, individually. Traced shapes are verified against reality on the first real load of each entry; a mismatch raises immediately.

Parameters:

Name	Type	Description	Default
dataset	Dataset	The underlying dataset returning Entry objects.	required
field_sizes	Union[Dict[str, int], Dict[str, Tuple[int, int]]]	Dictionary mapping field names to patch size. A single int is interpreted as (int, int).	required
same_shapes	bool	If True, assumes all entries share the same spatial dimensions and computes the grid only once.	False
shape_trace	bool	If True (default), try to obtain entry shapes via shape tracing before falling back to full loads. Set False to force the legacy full-load scan.	True
transforms	list	Optional list of callables applied to each patched Entry.	None

__len__()

Return the total number of patches across all entries.

take(amount: int, offset: int = 0) -> PatchedDataset

Subset the dataset to a specific range of patches (not implemented).

__get_full_image(entry_index: int) -> Any cached

Load and cache the full entry at the given index.

The first real load of each entry verifies its shapes against the traced/broadcast shapes used to build the patch grid.

__getitem__(idx) -> Any

Return the cropped Entry for the given patch index.

MSPatch dataclass

Patch spec for a multispectral Entry with dict-of-bands (coords are in REF-band pixels).

MultiSpectralPatchedDataset

Bases: Dataset

A patching dataset for multispectral entries with per-band spatial fields.

Patches are defined on a reference band and mapped to other bands by spatial ratio. Supports optional internal disk caching with cross-platform file locking for multi-process data loading.

Parameters:

Name	Type	Description	Default
dataset	Dataset	Underlying dataset returning multispectral Entry objects.	required
field_sizes	Union[Dict[str, int], Dict[str, Tuple[int, int]]]	Patch sizes per field, in reference-band pixels.	required
ref_band	str	Name of the reference band used to define the patch grid.	required
rounding	str	Rounding mode for coordinate mapping ("round", "floor", or "ceil").	'round'
use_internal_cache	bool	If True, patches are cached to disk after first generation.	False
clean_after_transfer	bool	If True, cached patch files are deleted after loading.	True

__len__()

Return the total number of patches across all entries.

take(amount: int, offset: int = 0) -> MultiSpectralPatchedDataset

Subset the dataset to amount patches starting at offset.

Parameters:

Name	Type	Description	Default
amount	int	Number of patches to keep.	required
offset	int	Starting patch index.	0

Returns:

Type	Description
MultiSpectralPatchedDataset	This dataset instance, modified in-place.

shuffle(seed: Optional[int] = None) -> MultiSpectralPatchedDataset

Randomly shuffle the patch order.

Parameters:

Name	Type	Description	Default
seed	Optional[int]	Optional random seed for reproducibility.	None

Returns:

Type	Description
MultiSpectralPatchedDataset	This dataset instance, modified in-place.

__getitem__(idx: int) -> Entry

Return the patched Entry at the given index.

Uses internal disk caching (if enabled) with cross-platform file locking to avoid redundant loading in multi-process settings.