nvidia.dali.fn.experimental.filter

nvidia.dali.fn.experimental.filter(__data, __filter, __fill_value=None, /, *, anchor=[-1], border='reflect_101', bytes_per_sample_hint=[0], dtype=None, mode='same', preserve=False, seed=-1, device=None, name=None)

Convolves the image with the provided filter.

Note

In fact, the operator computes a correlation, not a convolution, i.e. the order of filter elements is not flipped when computing the product of the filter and the image.

This operator allows sequence inputs.

Supported backends

  • ‘cpu’

  • ‘gpu’

Parameters:

  • __data (TensorList) –

    Batch of input samples.

    Sample can be an image, a video or volumetric (3D) data. Samples can contain channels: channel-first and channel-last layouts are supported. In case of video/sequences, the frame extent must preced the channels extent, i.e., for example, a video with "FCHW" layout is supported, but "CFHW" samples are not.

    Samples with the following types are supported: int8, int16, uint8, uint16, float16, float32.

    Please note that the intermediate type used for the computation is always float32.

    Note

    The CPU variant does not support volumetric (3D) data, nor inputs of types: int8 and float16.

  • __filter (TensorList) –

    Batch of filters.

    For inputs with two spatial dimensions (images or video), each filter must be a 2D array (or a sequence of 2D arrays to be applied per-frame to a video input). For volumetric inputs, the filter must be a 3D array. The filter values must have float32 type.

  • __fill_value (TensorList, optional) –

    Batch of scalars used for padding.

    If "border" is set to "constant", the input samples will be padded with the corresponding scalars when convolved with the filter. The scalars must be of the same type as the input samples. For video/sequence input, an array of scalars can be specified to be applied per-frame.

Keyword Arguments:

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

    Specifies the position of the filter over the input.

    If the filter size is (r, s) and the anchor is (a, b), the output at position (x, y) is a product of the filter and the input rectangle spanned between the corners: top-left (x - a, y - b) and bottom-right (x - a + r - 1, x - b + s - 1).

    If the -1 (the default) is specifed, the middle (rounded down to integer) of the filter extents is used, which, for odd sized filters, results in the filter centered over the input.

    The anchor must be, depending on the input dimensionality, a 2D or 3D point whose each extent lies within filter boundaries ([0, ..., filter_extent - 1]). The ordering of anchor’s extents corresponds to the order of filter’s extents.

    The parameter is ignored in "valid" mode. .

    Supports per-frame inputs.

  • border (str, optional, default = ‘reflect_101’) –

    Controls how to handle out-of-bound filter positions over the sample.

    Supported values are: "reflect_101", "reflect_1001", "wrap", "clamp", "constant".

    • "reflect_101" (default), reflects the input but does not repeat the outermost values (dcb|abcdefghi|hgf).

    • "reflect_1001": reflects the input including outermost values (cba|abcdefghi|ihg)

    • "wrap": wraps the input (ghi|abcdefghi|abc).

    • "clamp": the input is padded with outermost values (aaa|abcdefghi|iii).

    • "constant": the input is padded with the user-provided scalar (zeros by default). within the sample.

  • 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. The output type can either be float or must be same as input type. If not set, the input type is used.

    Note

    The intermediate type used for actual computation is float32. If the output is of integral type, the values will be clamped to the output type range.

  • mode (str, optional, default = ‘same’) –

    Supported values are: "same" and "valid".

    • "same" (default): The input and output sizes are the same and border is used to handle out-of-bound filter positions.

    • "valid": the output sample is cropped (by filter_extent - 1) so that all filter positions lie fully within the input sample.

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

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

    Random seed.

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