# nvidia.dali.fn.experimental.decoders.image_random_crop¶

nvidia.dali.fn.experimental.decoders.image_random_crop(*inputs, **kwargs)

Decodes images and randomly crops them.

The cropping window’s area (relative to the entire image) and aspect ratio can be restricted to a range of values specified by area and aspect_ratio arguments, respectively.

When possible, the operator uses the ROI decoding APIs (for example, libjpeg-turbo and nvJPEG) to reduce the decoding time and memory usage. When the ROI decoding is not supported for a given image format, it will decode the entire image and crop the selected ROI.

The output of the decoder is in HWC layout.

Supported formats: JPG, BMP, PNG, TIFF, PNM, PPM, PGM, PBM, JPEG 2000, WebP.

Note

JPEG 2000 region-of-interest (ROI) decoding is not accelerated on the GPU, and will use a CPU implementation regardless of the selected backend. For a GPU accelerated implementation, consider using separate decoders.image and random_crop operators.

Note

EXIF orientation metadata is used to rectify the image.

Supported backends
• ‘cpu’

• ‘mixed’

Parameters

input (TensorList) – Input to the operator.

Keyword Arguments
• adjust_orientation (bool, optional, default = True) – Use EXIF orientation metadata to rectify the images

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

Applies only to the mixed backend type.

If set to True, each thread in the internal thread pool will be tied to a specific CPU core. Otherwise, the threads can be reassigned to any CPU core by the operating system.

• 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.

• device_memory_padding (int, optional, default = 16777216) –

Applies only to the mixed backend type.

The padding for nvJPEG’s device memory allocations, in bytes. This parameter helps to avoid reallocation in nvJPEG when a larger image is encountered, and the internal buffer needs to be reallocated to decode the image.

If a value greater than 0 is provided, the operator preallocates one device buffer of the requested size per thread. If the value is correctly selected, no additional allocations will occur during the pipeline execution.

• device_memory_padding_jpeg2k (int, optional, default = 0) –

Applies only to the mixed backend type.

The padding for nvJPEG2k’s device memory allocations, in bytes. This parameter helps to avoid reallocation in nvJPEG2k when a larger image is encountered, and the internal buffer needs to be reallocated to decode the image.

If a value greater than 0 is provided, the operator preallocates the necessary number of buffers according to the hint provided. If the value is correctly selected, no additional allocations will occur during the pipeline execution.

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

Output data type of the image.

Values will be converted to the dynamic range of the requested type.

• host_memory_padding (int, optional, default = 8388608) –

Applies only to the mixed backend type.

The padding for nvJPEG’s host memory allocations, in bytes. This parameter helps to prevent the reallocation in nvJPEG when a larger image is encountered, and the internal buffer needs to be reallocated to decode the image.

If a value greater than 0 is provided, the operator preallocates two (because of double-buffering) host-pinned buffers of the requested size per thread. If selected correctly, no additional allocations will occur during the pipeline execution.

• host_memory_padding_jpeg2k (int, optional, default = 0) –

Applies only to the mixed backend type.

The padding for nvJPEG2k’s host memory allocations, in bytes. This parameter helps to prevent the reallocation in nvJPEG2k when a larger image is encountered, and the internal buffer needs to be reallocated to decode the image.

If a value greater than 0 is provided, the operator preallocates the necessary number of buffers according to the hint provided. If the value is correctly selected, no additional allocations will occur during the pipeline execution.

• hw_decoder_load (float, optional, default = 0.65) –

The percentage of the image data to be processed by the HW JPEG decoder.

Applies only to the mixed backend type in NVIDIA Ampere GPU architecture.

Determines the percentage of the workload that will be offloaded to the hardware decoder, if available. The optimal workload depends on the number of threads that are provided to the DALI pipeline and should be found empirically. More details can be found at https://developer.nvidia.com/blog/loading-data-fast-with-dali-and-new-jpeg-decoder-in-a100

• hybrid_huffman_threshold (int, optional, default = 1000000) –

Applies only to the mixed backend type.

Images with a total number of pixels (height * width) that is higher than this threshold will use the nvJPEG hybrid Huffman decoder. Images that have fewer pixels will use the nvJPEG host-side Huffman decoder.

Note

Hybrid Huffman decoder still largely uses the CPU.

• memory_stats (bool) –

Warning

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

• num_attempts (int, optional, default = 10) – Maximum number of attempts used to choose random area and aspect ratio.

• output_type (nvidia.dali.types.DALIImageType, optional, default = DALIImageType.RGB) –

The color space of the output image.

Note: When decoding to YCbCr, the image will be decoded to RGB and then converted to YCbCr, following the YCbCr definition from ITU-R BT.601.

• preallocate_height_hint (int, optional, default = 0) –

Image width hint.

Applies only to the mixed backend type in NVIDIA Ampere GPU architecture.

The hint is used to preallocate memory for the HW JPEG decoder.

• preallocate_width_hint (int, optional, default = 0) –

Image width hint.

Applies only to the mixed backend type in NVIDIA Ampere GPU architecture.

The hint is used to preallocate memory for the HW JPEG decoder.

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

• random_area (float or list of float, optional, default = [0.08, 1.0]) –

Range from which to choose random area fraction A.

The cropped image’s area will be equal to A * original image’s area.

• random_aspect_ratio (float or list of float, optional, default = [0.75, 1.333333]) – Range from which to choose random aspect ratio (width/height).

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

Random seed.

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

• split_stages (bool) –

Warning

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

• use_chunk_allocator (bool) –

Warning

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

• use_fast_idct (bool, optional, default = False) –

Enables fast IDCT in the libjpeg-turbo based CPU decoder, used when device is set to “cpu” or when the it is set to “mixed” but the particular image can not be handled by the GPU implementation.

According to the libjpeg-turbo documentation, decompression performance is improved by up to 14% with little reduction in quality.