nvidia.dali.fn.slice

nvidia.dali.fn.slice(__data, __anchor=None, __shape=None, /, *, axes=[1, 0], axis_names='WH', bytes_per_sample_hint=[0], dtype=None, end=None, fill_values=[0.0], normalized_anchor=True, normalized_shape=True, out_of_bounds_policy='error', preserve=False, rel_end=None, rel_shape=None, rel_start=None, seed=-1, shape=None, start=None, device=None, name=None)

Extracts a subtensor, or slice.

Note

For generic indexing and slicing you can use Python indexing syntax. See Indexing and Slicing for details.

The slice can be specified by proving the start and end coordinates, or start coordinates and shape of the slice. Both coordinates and shapes can be provided in absolute or relative terms.

The slice arguments can be specified by the following named arguments:

  1. start: Slice start coordinates (absolute)

  2. rel_start: Slice start coordinates (relative)

  3. end: Slice end coordinates (absolute)

  4. rel_end: Slice end coordinates (relative)

  5. shape: Slice shape (absolute)

  6. rel_shape: Slice shape (relative)

The slice can be configured by providing start and end coordinates or start and shape. Relative and absolute arguments can be mixed (for example, rel_start can be used with shape) as long as start and shape or end are uniquely defined.

Alternatively, two extra positional inputs can be provided, specifying anchor and shape. When using positional inputs, two extra boolean arguments normalized_anchor/normalized_shape can be used to specify the nature of the arguments provided. Using positional inputs for anchor and shape is incompatible with the named arguments specified above.

Note

For GPU backend and positional inputs anchor and shape, both CPU and GPU data nodes are accepted, though CPU inputs are preferred. Providing those arguments as GPU inputs will result in an additional device-to-host copy with its associated synchronization point. When possible, provide anchor and shape as CPU inputs.

The slice arguments should provide as many dimensions as specified by the axis_names or axes arguments.

By default, the nvidia.dali.fn.slice() operator uses normalized coordinates and WH order for the slice arguments.

This operator supports volumetric data.

Supported backends

  • ‘cpu’

  • ‘gpu’

Parameters:

  • __data (TensorList) – Batch that contains the input data.

  • __anchor (1D TensorList of float or int, optional) –

    (Optional) Input that contains normalized or absolute coordinates for the starting point of the slice (x0, x1, x2, …).

    Integer coordinates are interpreted as absolute coordinates, while float coordinates can be interpreted as absolute or relative coordinates, depending on the value of normalized_anchor.

  • __shape (1D TensorList of float or int, optional) –

    (Optional) Input that contains normalized or absolute coordinates for the dimensions of the slice (s0, s1, s2, …).

    Integer coordinates are interpreted as absolute coordinates, while float coordinates can be interpreted as absolute or relative coordinates, depending on the value of normalized_shape.

Keyword Arguments:

  • axes (int or list of int or TensorList of int, optional, default = [1, 0]) –

    Order of dimensions used for the anchor and shape slice inputs as dimension indices.

    Negative values are interpreted as counting dimensions from the back. Valid range: [-ndim, ndim-1], where ndim is the number of dimensions in the input data.

  • axis_names (layout str, optional, default = ‘WH’) –

    Order of the dimensions used for the anchor and shape slice inputs, as described in layout.

    If a value is provided, axis_names will have a higher priority than axes.

  • bytes_per_sample_hint (int or list of int, optional, default = [0]) –

    Output size hint, in bytes per sample.

    If specified, the operator’s outputs residing in GPU or page-locked host memory will be preallocated to accommodate a batch of samples of this size.

  • dtype (nvidia.dali.types.DALIDataType, optional) –

    Output data type.

    Supported types: FLOAT, FLOAT16, and UINT8.

    If not set, the input type is used.

  • end (int or list of int or TensorList of int, optional) –

    End coordinates of the slice.

    Note: Providing named arguments start, end, shape, rel_start, rel_end, rel_shape is incompatible with providing positional inputs anchor and shape.

  • fill_values (float or list of float, optional, default = [0.0]) –

    Determines padding values and is only relevant if out_of_bounds_policy is set to “pad”.

    If a scalar value is provided, it will be used for all the channels. If multiple values are provided, the number of values and channels must be identical (extent of dimension C in the layout) in the output slice.

  • image_type (nvidia.dali.types.DALIImageType) –

    Warning

    The argument image_type is no longer used and will be removed in a future release.

  • normalized_anchor (bool, optional, default = True) –

    Determines whether the anchor positional input should be interpreted as normalized (range [0.0, 1.0]) or as absolute coordinates.

    Note

    This argument is only relevant when anchor data type is float. For integer types, the coordinates are always absolute.

  • normalized_shape (bool, optional, default = True) –

    Determines whether the shape positional input should be interpreted as normalized (range [0.0, 1.0]) or as absolute coordinates.

    Note

    This argument is only relevant when anchor data type is float. For integer types, the coordinates are always absolute.

  • out_of_bounds_policy (str, optional, default = ‘error’) –

    Determines the policy when slicing the out of bounds area of the input.

    Here is a list of the supported values:

    • "error" (default): Attempting to slice outside of the bounds of the input will produce an error.

    • "pad": The input will be padded as needed with zeros or any other value that is specified with the fill_values argument.

    • "trim_to_shape": The slice window will be cut to the bounds of the input.

  • preserve (bool, optional, default = False) – Prevents the operator from being removed from the graph even if its outputs are not used.

  • rel_end (float or list of float or TensorList of float, optional) –

    End relative coordinates of the slice (range [0.0 - 1.0].

    Note: Providing named arguments start, end, shape, rel_start, rel_end, rel_shape is incompatible with providing positional inputs anchor and shape.

  • rel_shape (float or list of float or TensorList of float, optional) –

    Relative shape of the slice (range [0.0 - 1.0]).

    Providing named arguments start, end, shape, rel_start, rel_end, rel_shape is incompatible with providing positional inputs anchor and shape.

  • rel_start (float or list of float or TensorList of float, optional) –

    Start relative coordinates of the slice (range [0.0 - 1.0]).

    Note: Providing named arguments start, end, shape, rel_start, rel_end, rel_shape is incompatible with providing positional inputs anchor and shape.

  • seed (int, optional, default = -1) –

    Random seed.

    If not provided, it will be populated based on the global seed of the pipeline.

  • shape (int or list of int or TensorList of int, optional) –

    Shape of the slice.

    Providing named arguments start, end, shape, rel_start, rel_end, rel_shape is incompatible with providing positional inputs anchor and shape.

  • start (int or list of int or TensorList of int, optional) –

    Start coordinates of the slice.

    Note: Providing named arguments start/end or start/shape is incompatible with providing positional inputs anchor and shape.

  • output_dtype (nvidia.dali.types.DALIDataType) –

    Warning

    The argument output_dtype is a deprecated alias for dtype. Use dtype instead.