Image Preprocessing¶

Classes:

Name	Description
`ImagePipeline`	An ordered list of image preprocessing steps for a fixed frame geometry.
`Crop`	Extract a fixed region of interest from each frame.
`Downsample`	Average each `factor x factor` block of pixels into one output pixel.
`Grayscale`	Collapse the channels to one, as a weighted per-pixel sum.

dg.preprocess.ImagePipeline ¶

ImagePipeline(
    steps: list[Step],
    height: int,
    width: int,
    channels: int,
)

An ordered list of image preprocessing steps for a fixed frame geometry.

height, width, and channels describe the frame the deployed model expects from the sensor, as uint8 pixels in HWC layout. Call features to precompute training features, and pass the same pipeline to dg.export(model, preprocess=pipe) so training and deployed inference run identical steps. Training frames must match the geometry exactly, so resize variable-size datasets during dataset prep.

Parameters:

Name	Type	Description	Default
`steps`	`list[Step]`	Ordered preprocessing steps.	required
`height`	`int`	Sensor frame height in pixels.	required
`width`	`int`	Sensor frame width in pixels.	required
`channels`	`int`	Number of color channels.	required

Methods:

Name	Description
`features`	Precompute a whole dataset's training features.

features ¶

features(
    source: Tensor | Dataset,
    *,
    batch_size: int = 1024,
    num_workers: int = 0
) -> torch.Tensor

Precompute a whole dataset's training features.

Runs the pipeline once over the dataset rather than once per epoch. Wrap the returned tensor in a TensorDataset to train on it, and apply any augmentation on top of it rather than inside this call.

Inputs must match the shape and dtype this pipeline is configured for, so a train/deploy mismatch fails here. A Dataset yielding (sample, label) pairs has the label dropped; labels stay yours to keep track of.

Parameters:

Name	Type	Description	Default
`source`	`Tensor \| Dataset`	Stacked raw inputs, or a Dataset of raw samples.	required
`batch_size`	`int`	Samples per pipeline call. Lower it if memory is tight.	`1024`
`num_workers`	`int`	DataLoader workers for a Dataset source. Worth setting when decoding the samples dominates (JPEG frames, WAV clips).	`0`

Returns:

Type	Description
`Tensor`	The features in PyTorch's NCHW layout: `[N, C, H, W]` for images, `[N, 1, T, features]` for framed audio.

Raises:

Type	Description
`ValueError`	If `source` is empty.

dg.preprocess.Crop ¶

Crop(
    height: int,
    width: int,
    top: int | None = None,
    left: int | None = None,
)

Extract a fixed region of interest from each frame.

With top and left omitted, the crop is centered on the incoming frame. The region must lie inside the frame.

Parameters:

Name	Type	Description	Default
`height`	`int`	Output height.	required
`width`	`int`	Output width.	required
`top`	`int \| None`	Row offset (centers if omitted).	`None`
`left`	`int \| None`	Column offset (centers if omitted).	`None`

dg.preprocess.Downsample ¶

Downsample(factor: int)

Average each factor x factor block of pixels into one output pixel.

Frame height and width must both be divisible by factor. Crop first with dg.preprocess.Crop if they are not. Only whole-number factors are supported.

Parameters:

Name	Type	Description	Default
`factor`	`int`	Downsampling factor (must be >= 2).	required

dg.preprocess.Grayscale ¶

Grayscale(weights: tuple[float, ...] = GRAYSCALE_BT601)

Collapse the channels to one, as a weighted per-pixel sum.

weights must sum to 1, and default to ITU-R BT.601 luma, the standard RGB-to-grayscale coefficients.

Parameters:

Name	Type	Description	Default
`weights`	`tuple[float, ...]`	Grayscale conversion weights summing to 1 (default: ITU-R BT.601 luma).	`GRAYSCALE_BT601`