image_normalizer

image_normalizer

create_image_normalizer

create_image_normalizer(input_min, input_max, input_mean, input_std, norm_type, device=None, standardization_mean=None, standardization_std=None)

Create image normalizer with linear scaling and optional standardization.

Note

The function handles RGB (multi-channel) and depth (single-channel) normalization: 1. Linear scaling from [input_min, input_max] to [output_min, output_max] 2. Optional standardization using provided mean/std (e.g., ImageNet stats)

Parameters:

Name	Type	Description	Default
input_min	float | ndarray	Minimum value(s) in input range (scalar or per-channel array)	required
input_max	float | ndarray	Maximum value(s) in input range (scalar or per-channel array)	required
input_mean	float | ndarray	Mean of input data (scalar or per-channel array)	required
input_std	float | ndarray	Standard deviation of input data (scalar or per-channel array)	required
norm_type	str	Normalization type (from ImageNormalizationType or DepthNormalizationType)	required
device	device | None	Target device for tensors	None
standardization_mean	float | ndarray | None	Mean for optional second-stage standardization. Defaults to pretrained RGB stats for CLIP normalization.	None
standardization_std	float | ndarray | None	Std for optional second-stage standardization. Defaults to pretrained RGB stats for CLIP normalization.	None

Returns:

Type	Description
LinearNormalizer | SequentialNormalizer	SingleFieldLinearNormalizer for scaling, or SequentialNormalizer for scaling + standardization.

Source code in src/versatil/data/normalization/image_normalizer.py

def create_image_normalizer(
    input_min: float | np.ndarray,
    input_max: float | np.ndarray,
    input_mean: float | np.ndarray,
    input_std: float | np.ndarray,
    norm_type: str,
    device: torch.device | None = None,
    standardization_mean: float | np.ndarray | None = None,
    standardization_std: float | np.ndarray | None = None,
) -> LinearNormalizer | SequentialNormalizer:
    """Create image normalizer with linear scaling and optional standardization.

    Note:
        The function handles RGB (multi-channel) and depth (single-channel) normalization:
        1. Linear scaling from [input_min, input_max] to [output_min, output_max]
        2. Optional standardization using provided mean/std (e.g., ImageNet stats)

    Args:
        input_min: Minimum value(s) in input range (scalar or per-channel array)
        input_max: Maximum value(s) in input range (scalar or per-channel array)
        input_mean: Mean of input data (scalar or per-channel array)
        input_std: Standard deviation of input data (scalar or per-channel array)
        norm_type: Normalization type (from ImageNormalizationType or DepthNormalizationType)
        device: Target device for tensors
        standardization_mean: Mean for optional second-stage standardization.
            Defaults to pretrained RGB stats for CLIP normalization.
        standardization_std: Std for optional second-stage standardization.
            Defaults to pretrained RGB stats for CLIP normalization.

    Returns:
        SingleFieldLinearNormalizer for scaling, or SequentialNormalizer for scaling + standardization.
    """
    output_min, output_max = _get_output_range(norm_type)
    if (standardization_mean is None) != (standardization_std is None):
        raise ValueError(
            "standardization_mean and standardization_std must be provided together"
        )

    if (
        standardization_mean is None
        and standardization_std is None
        and norm_type in _RGB_ONLY_STANDARDIZATION_TYPES
    ):
        standardization_mean, standardization_std = _RGB_STANDARDIZATION_STATS[
            norm_type
        ]

    stage1 = _create_linear_scaling_normalizer(
        input_min=input_min,
        input_max=input_max,
        input_mean=input_mean,
        input_std=input_std,
        output_min=output_min,
        output_max=output_max,
        device=device,
    )

    if standardization_mean is not None and standardization_std is not None:
        scaled_mean = _compute_scaled_values(
            input_mean, input_min, input_max, output_min, output_max
        )
        scaled_std = _compute_scaled_values(
            input_std, input_min, input_max, output_min, output_max, is_std=True
        )
        stage2_input_min = _broadcast_to_reference_shape(
            output_min, standardization_mean
        )
        stage2_input_max = _broadcast_to_reference_shape(
            output_max, standardization_mean
        )
        stage2_input_mean = _broadcast_to_reference_shape(
            scaled_mean, standardization_mean
        )
        stage2_input_std = _broadcast_to_reference_shape(
            scaled_std, standardization_mean
        )

        stage2 = _create_standardization_normalizer(
            input_min=stage2_input_min,
            input_max=stage2_input_max,
            input_mean=stage2_input_mean,
            input_std=stage2_input_std,
            standardization_mean=standardization_mean,
            standardization_std=standardization_std,
            device=device,
        )
        return SequentialNormalizer(normalizers=[stage1, stage2])

    return stage1

get_rgb_image_normalizer

get_rgb_image_normalizer(norm_type=value, device=None)

Create normalizer for RGB images in [0, 1] range.

Assumes images have already been converted from uint8 to float32 via /255. For IMAGENET and CLIP types, applies per-channel standardization directly without an additional scaling stage.

Parameters:

Name	Type	Description	Default
norm_type	str	Type of normalization.	value
device	device | None	Target device for tensors	None

Returns:

Type	Description
SingleFieldLinearNormalizer | SequentialNormalizer	Configured normalizer

Source code in src/versatil/data/normalization/image_normalizer.py

def get_rgb_image_normalizer(
    norm_type: str = ImageNormalizationType.ZERO_TO_ONE.value,
    device: torch.device | None = None,
) -> SingleFieldLinearNormalizer | SequentialNormalizer:
    """Create normalizer for RGB images in [0, 1] range.

    Assumes images have already been converted from uint8 to float32 via /255.
    For IMAGENET and CLIP types, applies per-channel standardization
    directly without an additional scaling stage.

    Args:
        norm_type: Type of normalization.
        device: Target device for tensors

    Returns:
        Configured normalizer
    """
    if norm_type in _RGB_STANDARDIZATION_STATS:
        standardization_mean, standardization_std = _RGB_STANDARDIZATION_STATS[
            norm_type
        ]
        return _create_standardization_normalizer(
            input_min=np.zeros(3, dtype=np.float32),
            input_max=np.ones(3, dtype=np.float32),
            input_mean=np.full(3, 0.5, dtype=np.float32),
            input_std=np.full(3, np.sqrt(1.0 / 12.0), dtype=np.float32),
            standardization_mean=np.array(standardization_mean, dtype=np.float32),
            standardization_std=np.array(standardization_std, dtype=np.float32),
            device=device,
        )

    input_min = 0.0
    input_max = 1.0
    input_mean = 0.5
    input_std = np.sqrt(1.0 / 12.0)

    return create_image_normalizer(
        input_min=input_min,
        input_max=input_max,
        input_mean=input_mean,
        input_std=input_std,
        norm_type=norm_type,
        device=device,
    )

get_depth_image_normalizer

get_depth_image_normalizer(input_min, input_max, input_mean, input_std, norm_type=value, device=None)

Create normalizer for depth images.

Convenience wrapper around create_image_normalizer for depth images. Handles IMAGENET normalization by adding appropriate standardization.

Parameters:

Name	Type	Description	Default
input_min	float	Minimum depth value in dataset	required
input_max	float	Maximum depth value in dataset	required
input_mean	float	Mean depth value in dataset	required
input_std	float	Standard deviation of depth values	required
norm_type	str	Type of normalization	value
device	device | None	Target device for tensors	None

Returns:

Type	Description
SingleFieldLinearNormalizer | SequentialNormalizer	Configured normalizer

Source code in src/versatil/data/normalization/image_normalizer.py

def get_depth_image_normalizer(
    input_min: float,
    input_max: float,
    input_mean: float,
    input_std: float,
    norm_type: str = ImageNormalizationType.ZERO_TO_ONE.value,
    device: torch.device | None = None,
) -> SingleFieldLinearNormalizer | SequentialNormalizer:
    """Create normalizer for depth images.

    Convenience wrapper around create_image_normalizer for depth images.
    Handles IMAGENET normalization by adding appropriate standardization.

    Args:
        input_min: Minimum depth value in dataset
        input_max: Maximum depth value in dataset
        input_mean: Mean depth value in dataset
        input_std: Standard deviation of depth values
        norm_type: Type of normalization
        device: Target device for tensors

    Returns:
        Configured normalizer
    """
    if norm_type in {
        ImageNormalizationType.CLIP.value,
    }:
        raise ValueError(
            f"Depth normalization type '{norm_type}' is RGB-only. "
            f"Use one of: {[ImageNormalizationType.ZERO_TO_ONE.value, ImageNormalizationType.MINUS_ONE_TO_ONE.value, ImageNormalizationType.IMAGENET.value]}"
        )
    if norm_type == ImageNormalizationType.IMAGENET.value:
        standardization_mean = IMAGENET_DEPTH_MEAN
        standardization_std = IMAGENET_DEPTH_STD
    else:
        standardization_mean = None
        standardization_std = None

    return create_image_normalizer(
        input_min=input_min,
        input_max=input_max,
        input_mean=input_mean,
        input_std=input_std,
        norm_type=norm_type,
        device=device,
        standardization_mean=standardization_mean,
        standardization_std=standardization_std,
    )

get_range_normalizer_from_stat

get_range_normalizer_from_stat(stat, output_max=1.0, output_min=-1.0, range_eps=1e-07)

Create normalizer from pre-computed statistics.

Parameters:

Name	Type	Description	Default
stat	dict	Dictionary with 'min', 'max', 'mean', 'std' keys	required
output_max	float	Maximum value of output range	1.0
output_min	float	Minimum value of output range	-1.0
range_eps	float	Epsilon for handling zero-range dimensions	1e-07

Returns:

Type	Description
SingleFieldLinearNormalizer	Configured normalizer

Source code in src/versatil/data/normalization/image_normalizer.py

def get_range_normalizer_from_stat(
    stat: dict,
    output_max: float = 1.0,
    output_min: float = -1.0,
    range_eps: float = 1e-7,
) -> SingleFieldLinearNormalizer:
    """Create normalizer from pre-computed statistics.

    Args:
        stat: Dictionary with 'min', 'max', 'mean', 'std' keys
        output_max: Maximum value of output range
        output_min: Minimum value of output range
        range_eps: Epsilon for handling zero-range dimensions

    Returns:
        Configured normalizer
    """
    input_max = stat["max"]
    input_min = stat["min"]
    input_range = input_max - input_min
    ignore_dim = input_range < range_eps
    input_range[ignore_dim] = output_max - output_min
    scale = (output_max - output_min) / input_range
    offset = output_min - scale * input_min
    offset[ignore_dim] = (output_max + output_min) / 2 - input_min[ignore_dim]

    return SingleFieldLinearNormalizer.create_manual(
        scale=scale, offset=offset, input_stats_dict=stat
    )

array_to_stats

array_to_stats(arr)

Convert array to statistics dictionary.

Parameters:

Name	Type	Description	Default
arr	ndarray	Input array	required

Returns:

Type	Description
dict	Dictionary with min, max, mean, std

Source code in src/versatil/data/normalization/image_normalizer.py

def array_to_stats(arr: np.ndarray) -> dict:
    """Convert array to statistics dictionary.

    Args:
        arr: Input array

    Returns:
        Dictionary with min, max, mean, std
    """
    stat = {
        "min": np.min(arr, axis=0),
        "max": np.max(arr, axis=0),
        "mean": np.mean(arr, axis=0),
        "std": np.std(arr, axis=0),
    }
    return stat