Functional API

Quick start

Warning

This API is experimental and subject to change without notice!

Functional API is designed to simplify the usage of DALI operators in a psuedo-imperative way. It exposes operators as functions, with ths same name as the operator class, but converted to snake_case - for example ops.FileReader will be exposed as fn.file_reader().

Example:

import nvidia.dali as dali

pipe = dali.pipeline.Pipeline(batch_size = 3, num_threads = 2, device_id = 0)
with pipe:
    files, labels = dali.fn.file_reader(file_root = "./my_file_root")
    images = dali.fn.image_decoder(files, device = "mixed")
    images = dali.fn.rotate(images, angle = dali.fn.uniform(range=(-45,45)))
    images = dali.fn.resize(images, resize_x = 300, resize_y = 300)
    pipe.set_outputs(images, labels)

pipe.build()
outputs = pipe.run()

The use of functional API does not change other aspects of pipeline definition - the functions still operate on and return pipeline.DataNode objects.

Interoperability with operator objects

Functional API is, for the major part, only a wrapper around operator objects - as such, it is inherently compatible with the object-based API. The following example mixes the two, using object API to pre-configure a file reader and a resize operator:

pipe = dali.pipeline.Pipeline(batch_size = 3, num_threads = 2, device_id = 0)
reader = dali.ops.FileReader(file_root = ".")
resize = dali.ops.Resize(device = "gpu", resize_x = 300, resize_y = 300)

with pipe:
    files, labels = reader()
    images = dali.fn.image_decoder(files, device = "mixed")
    images = dali.fn.rotate(images, angle = dali.fn.uniform(range=(-45,45)))
    images = resize(images)
    pipe.set_outputs(images, labels)

pipe.build()
outputs = pipe.run()

Functions

nvidia.dali.fn.audio_decoder(*inputs, **arguments)

see nvidia.dali.ops.AudioDecoder

nvidia.dali.fn.bb_flip(*inputs, **arguments)

see nvidia.dali.ops.BbFlip

nvidia.dali.fn.bbox_paste(*inputs, **arguments)

see nvidia.dali.ops.BBoxPaste

nvidia.dali.fn.box_encoder(*inputs, **arguments)

see nvidia.dali.ops.BoxEncoder

nvidia.dali.fn.brightness(*inputs, **arguments)

see nvidia.dali.ops.Brightness

nvidia.dali.fn.brightness_contrast(*inputs, **arguments)

see nvidia.dali.ops.BrightnessContrast

nvidia.dali.fn.caffe2_reader(*inputs, **arguments)

see nvidia.dali.ops.Caffe2Reader

nvidia.dali.fn.caffe_reader(*inputs, **arguments)

see nvidia.dali.ops.CaffeReader

nvidia.dali.fn.cast(*inputs, **arguments)

see nvidia.dali.ops.Cast

nvidia.dali.fn.coco_reader(*inputs, **arguments)

see nvidia.dali.ops.COCOReader

nvidia.dali.fn.coin_flip(*inputs, **arguments)

see nvidia.dali.ops.CoinFlip

nvidia.dali.fn.color_space_conversion(*inputs, **arguments)

see nvidia.dali.ops.ColorSpaceConversion

nvidia.dali.fn.color_twist(*inputs, **arguments)

see nvidia.dali.ops.ColorTwist

nvidia.dali.fn.constant(*inputs, **arguments)

see nvidia.dali.ops.Constant

nvidia.dali.fn.contrast(*inputs, **arguments)

see nvidia.dali.ops.Contrast

nvidia.dali.fn.coord_flip(*inputs, **arguments)

see nvidia.dali.ops.CoordFlip

nvidia.dali.fn.coord_transform(*inputs, **arguments)

see nvidia.dali.ops.CoordTransform

nvidia.dali.fn.copy(*inputs, **arguments)

see nvidia.dali.ops.Copy

nvidia.dali.fn.crop(*inputs, **arguments)

see nvidia.dali.ops.Crop

nvidia.dali.fn.crop_mirror_normalize(*inputs, **arguments)

see nvidia.dali.ops.CropMirrorNormalize

nvidia.dali.fn.dl_tensor_python_function(*inputs, **arguments)

see nvidia.dali.ops.DLTensorPythonFunction

nvidia.dali.fn.dump_image(*inputs, **arguments)

see nvidia.dali.ops.DumpImage

nvidia.dali.fn.element_extract(*inputs, **arguments)

see nvidia.dali.ops.ElementExtract

nvidia.dali.fn.erase(*inputs, **arguments)

see nvidia.dali.ops.Erase

nvidia.dali.fn.external_source(source=None, num_outputs=None, *, cycle=None, name=None, device='cpu', layout=None, cuda_stream=None, use_copy_kernel=None, **kwargs)

Creates a data node which is populated with data from a Python source. The data can be provided by the source function or iterable, or it can be provided by pipeline.feed_input(name, data, layout, cuda_stream) inside pipeline.iter_setup.

In the case of the GPU input, it is the user responsibility to modify the provided GPU memory content only using provided stream (DALI schedules a copy on it and all work is properly queued). If no stream is provided feeding input blocks until the provided memory is copied to the internal buffer.

Warning

nvidia.dali.ops.ExternalSource() operator is not compatible with TensorFlow integration.

Note

To return a batch of copies of the same tensor, use nvidia.dali.types.Constant(), which is more performant.

Parameters

• source (callable or iterable) –

  The source of the data.

  The source is polled for data (via a call source() or next(source)) when the pipeline needs input for the next iteration. Depending on the value of num_outputs, the source can supply one or more data batches. If num_outputs is not set, the source is expected to return one batch. If this value is specified, the data is expected to a be tuple, or list, where each element corresponds to respective return value of the external_source. If the source is a callable that accepts a positional argument, it is assumed to be the current iteration number and consecutive calls will be source(0), source(1), and so on. If the source is a generator function, the function is invoked and treated as an iterable. However, unlike a generator, the function can be used with cycle. In this case, the function will be called again when the generator reaches the end of iteration.

  For the GPU input, it is a user’s responsibility to modify the provided GPU memory content only in the provided stream. DALI schedules a copy on this stream, and all work is properly queued. If no stream is provided, DALI will use a default, with a best-effort approach at correctness. See the cuda_stream argument documentation for more information. The data batch produced by source may be anything that’s accepted by nvidia.dali.pipeline.Pipeline.feed_input()

• num_outputs (int, optional) – If specified, denotes the number of TensorLists that are produced by the source function.

Keyword Arguments

• cycle (bool) –

  If set to True, the source will be wrapped.

  If set to False, StopIteration is raised when the end of data is reached. This flag requires that the source is a collection, for example, an iterable object where iter(source) returns a fresh iterator on each call or a gensource erator function. In the latter case, the generator function is called again when more data than was yielded by the function is requested.

• name (str, optional) –

  The name of the data node.

  Used when feeding the data in iter_setup and can be omitted if the data is provided by source.

layoutlayout str or list/tuple thereof

If provided, sets the layout of the data.

When num_outputs > 1, the layout can be a list that contains a distinct layout for each output. If the list has fewer than num_outputs elements, only the first outputs have the layout set, the rest of the outputs don’t have a layout set.

cuda_streamoptional, cudaStream_t or an object convertible to cudaStream_t, such as cupy.cuda.Stream or torch.cuda.Stream

The CUDA stream is used to copy data to the GPU or from a GPU source.

If this parameter is not set, a best-effort will be taken to maintain correctness. That is, if the data is provided as a tensor/array from a recognized library such as CuPy or PyTorch, the library’s current stream is used. Although this approach works in typical scenarios, with advanced use cases, and code that uses unsupported libraries, you might need to explicitly supply the stream handle.

This argument has two special values:

• 0 - Use the default CUDA stream

• 1 - Use DALI’s internal stream

If internal stream is used, the call to feed_input will block until the copy to internal buffer is complete, since there’s no way to synchronize with this stream to prevent overwriting the array with new data in another stream.

use_copy_kerneloptional, bool

If set to True, DALI will use a CUDA kernel to feed the data instead of cudaMemcpyAsync (default).

Note

This is applicable only when copying data to and from GPU memory.

blockingoptional

Determines whether the external source should wait until data is available or just fail when the data is not available.

no_copyoptional

Determines whether DALI should copy the buffer when feed_input is called.

If set to True, DALI passes the user memory directly to the pipeline, instead of copying it. It is the user responsibility to keep the buffer alive and unmodified until it is consumed by the pipeline.

The buffer can be modified or freed again after the output of the relevant iterations has been consumed. Effectively, it happens after prefetch_queue_depth or cpu_queue_depth * gpu_queue_depth (when they are not equal) iterations following the feed_input call.

The memory location must match the specified device parameter of the operator. For the CPU, the provided memory can be one contiguous buffer or a list of contiguous Tensors. For the GPU, to avoid extra copy, the provided buffer must be contiguous. If you provide a list of separate Tensors, there will be an additional copy made internally, consuming both memory and bandwidth.

nvidia.dali.fn.fast_resize_crop_mirror(*inputs, **arguments)

see nvidia.dali.ops.FastResizeCropMirror

nvidia.dali.fn.file_reader(*inputs, **arguments)

see nvidia.dali.ops.FileReader

nvidia.dali.fn.flip(*inputs, **arguments)

see nvidia.dali.ops.Flip

nvidia.dali.fn.gaussian_blur(*inputs, **arguments)

see nvidia.dali.ops.GaussianBlur

nvidia.dali.fn.hsv(*inputs, **arguments)

see nvidia.dali.ops.Hsv

nvidia.dali.fn.hue(*inputs, **arguments)

see nvidia.dali.ops.Hue

nvidia.dali.fn.image_decoder(*inputs, **arguments)

see nvidia.dali.ops.ImageDecoder

nvidia.dali.fn.image_decoder_crop(*inputs, **arguments)

see nvidia.dali.ops.ImageDecoderCrop

nvidia.dali.fn.image_decoder_random_crop(*inputs, **arguments)

see nvidia.dali.ops.ImageDecoderRandomCrop

nvidia.dali.fn.image_decoder_slice(*inputs, **arguments)

see nvidia.dali.ops.ImageDecoderSlice

nvidia.dali.fn.jitter(*inputs, **arguments)

see nvidia.dali.ops.Jitter

nvidia.dali.fn.lookup_table(*inputs, **arguments)

see nvidia.dali.ops.LookupTable

nvidia.dali.fn.mel_filter_bank(*inputs, **arguments)

see nvidia.dali.ops.MelFilterBank

nvidia.dali.fn.mfc(*inputs, **arguments)

see nvidia.dali.ops.MFCC

nvidia.dali.fn.mxnet_reader(*inputs, **arguments)

see nvidia.dali.ops.MXNetReader

nvidia.dali.fn.nemo_asr_reader(*inputs, **arguments)

see nvidia.dali.ops.NemoAsrReader

nvidia.dali.fn.nonsilent_region(*inputs, **arguments)

see nvidia.dali.ops.NonsilentRegion

nvidia.dali.fn.normal_distribution(*inputs, **arguments)

see nvidia.dali.ops.NormalDistribution

nvidia.dali.fn.normalize(*inputs, **arguments)

see nvidia.dali.ops.Normalize

nvidia.dali.fn.numpy_reader(*inputs, **arguments)

see nvidia.dali.ops.NumpyReader

nvidia.dali.fn.old_color_twist(*inputs, **arguments)

see nvidia.dali.ops.OldColorTwist

nvidia.dali.fn.one_hot(*inputs, **arguments)

see nvidia.dali.ops.OneHot

nvidia.dali.fn.optical_flow(*inputs, **arguments)

see nvidia.dali.ops.OpticalFlow

nvidia.dali.fn.pad(*inputs, **arguments)

see nvidia.dali.ops.Pad

nvidia.dali.fn.paste(*inputs, **arguments)

see nvidia.dali.ops.Paste

nvidia.dali.fn.peek_image_shape(*inputs, **arguments)

see nvidia.dali.ops.PeekImageShape

nvidia.dali.fn.power_spectrum(*inputs, **arguments)

see nvidia.dali.ops.PowerSpectrum

nvidia.dali.fn.preemphasis_filter(*inputs, **arguments)

see nvidia.dali.ops.PreemphasisFilter

nvidia.dali.fn.python_function(*inputs, **arguments)

see nvidia.dali.ops.PythonFunction

nvidia.dali.fn.random_bbox_crop(*inputs, **arguments)

see nvidia.dali.ops.RandomBBoxCrop

nvidia.dali.fn.random_resized_crop(*inputs, **arguments)

see nvidia.dali.ops.RandomResizedCrop

nvidia.dali.fn.reinterpret(*inputs, **arguments)

see nvidia.dali.ops.Reinterpret

nvidia.dali.fn.reshape(*inputs, **arguments)

see nvidia.dali.ops.Reshape

nvidia.dali.fn.resize(*inputs, **arguments)

see nvidia.dali.ops.Resize

nvidia.dali.fn.resize_crop_mirror(*inputs, **arguments)

see nvidia.dali.ops.ResizeCropMirror

nvidia.dali.fn.rotate(*inputs, **arguments)

see nvidia.dali.ops.Rotate

nvidia.dali.fn.saturation(*inputs, **arguments)

see nvidia.dali.ops.Saturation

nvidia.dali.fn.sequence_reader(*inputs, **arguments)

see nvidia.dali.ops.SequenceReader

nvidia.dali.fn.sequence_rearrange(*inputs, **arguments)

see nvidia.dali.ops.SequenceRearrange

nvidia.dali.fn.shapes(*inputs, **arguments)

see nvidia.dali.ops.Shapes

nvidia.dali.fn.slice(*inputs, **arguments)

see nvidia.dali.ops.Slice

nvidia.dali.fn.spectrogram(*inputs, **arguments)

see nvidia.dali.ops.Spectrogram

nvidia.dali.fn.sphere(*inputs, **arguments)

see nvidia.dali.ops.Sphere

nvidia.dali.fn.ssd_random_crop(*inputs, **arguments)

see nvidia.dali.ops.SSDRandomCrop

nvidia.dali.fn.tfrecord_reader(*inputs, **arguments)

see nvidia.dali.ops.TFRecordReader

nvidia.dali.fn.to_decibels(*inputs, **arguments)

see nvidia.dali.ops.ToDecibels

nvidia.dali.fn.translate_transform(*inputs, **arguments)

see nvidia.dali.ops.TranslateTransform

nvidia.dali.fn.transpose(*inputs, **arguments)

see nvidia.dali.ops.Transpose

nvidia.dali.fn.uniform(*inputs, **arguments)

see nvidia.dali.ops.Uniform

nvidia.dali.fn.video_reader(*inputs, **arguments)

see nvidia.dali.ops.VideoReader

nvidia.dali.fn.video_reader_resize(*inputs, **arguments)

see nvidia.dali.ops.VideoReaderResize

nvidia.dali.fn.warp_affine(*inputs, **arguments)

see nvidia.dali.ops.WarpAffine

nvidia.dali.fn.water(*inputs, **arguments)

see nvidia.dali.ops.Water