Types

TensorList

TensorList represents a batch of tensors. TensorLists are the return values of Pipeline.run or Pipeline.share_outputs

TensorListCPU

class nvidia.dali.backend.TensorListCPU
__getitem__(self: nvidia.dali.backend_impl.TensorListCPU, i: int) → nvidia.dali.backend_impl.TensorCPU

Returns a tensor at given position i in the list.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: nvidia.dali.backend_impl.TensorListCPU, object: capsule, layout: str = ‘’) -> None

    List of tensors residing in the CPU memory.

    objectDLPack object

    Python DLPack object representing TensorList

    layoutstr

    Layout of the data

  2. __init__(self: nvidia.dali.backend_impl.TensorListCPU, tl: nvidia.dali.backend_impl.TensorListCPU, layout: object = None) -> None

  3. __init__(self: nvidia.dali.backend_impl.TensorListCPU, b: buffer, layout: str = ‘’, is_pinned: bool = False) -> None

    List of tensors residing in the CPU memory.

    bobject

    the buffer to wrap into the TensorListCPU object

    layoutstr

    Layout of the data

    is_pinnedbool

    If provided memory is page-locked (pinned)

as_array(self: nvidia.dali.backend_impl.TensorListCPU) → array

Returns TensorList as a numpy array. TensorList must be dense.

as_reshaped_tensor(self: nvidia.dali.backend_impl.TensorListCPU, arg0: List[int]) → nvidia.dali.backend_impl.TensorCPU

Returns a tensor that is a view of this TensorList cast to the given shape.

This function can only be called if TensorList is contiguous in memory and the volumes of requested Tensor and TensorList matches.

as_tensor(self: nvidia.dali.backend_impl.TensorListCPU) → nvidia.dali.backend_impl.TensorCPU

Returns a tensor that is a view of this TensorList.

This function can only be called if is_dense_tensor returns True.

at(self: nvidia.dali.backend_impl.TensorListCPU, arg0: int) → array

Returns tensor at given position in the list.

copy_to_external(self: nvidia.dali.backend_impl.TensorListCPU, arg0: object) → None

Copy the contents of this TensorList to an external pointer (of type ctypes.c_void_p) residing in CPU memory.

This function is used internally by plugins to interface with tensors from supported Deep Learning frameworks.

data_ptr(self: nvidia.dali.backend_impl.TensorListCPU) → object

Returns the address of the first element of TensorList.

is_dense_tensor(self: nvidia.dali.backend_impl.TensorListCPU) → bool

Checks whether all tensors in this TensorList have the same shape (and so the list itself can be viewed as a tensor).

For example, if TensorList contains N tensors, each with shape (H,W,C) (with the same values of H, W and C), then the list may be viewed as a tensor of shape (N, H, W, C).

layout(self: nvidia.dali.backend_impl.TensorListCPU) → str

TensorListGPU

class nvidia.dali.backend.TensorListGPU
__getitem__(self: nvidia.dali.backend_impl.TensorListGPU, i: int) → nvidia.dali.backend_impl.TensorGPU

Returns a tensor at given position i in the list.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: nvidia.dali.backend_impl.TensorListGPU, object: capsule, layout: str = ‘’) -> None

    List of tensors residing in the GPU memory.

    objectDLPack object

    Python DLPack object representing TensorList

    layoutstr

    Layout of the data

  2. __init__(self: nvidia.dali.backend_impl.TensorListGPU, tl: nvidia.dali.backend_impl.TensorListGPU, layout: object = None) -> None

  3. __init__(self: nvidia.dali.backend_impl.TensorListGPU, object: object, layout: str = ‘’, device_id: int = -1) -> None

    List of tensors residing in the GPU memory.

    objectobject

    Python object that implement CUDA Array Interface

    layoutstr

    Layout of the data

    device_idint

    Device of where this tensor resides. If not provided, the current device is used.

  4. __init__(self: nvidia.dali.backend_impl.TensorListGPU) -> None

    List of tensors residing in the GPU memory.

as_cpu(self: nvidia.dali.backend_impl.TensorListGPU) → nvidia.dali.backend_impl.TensorListCPU

Returns a TensorListCPU object being a copy of this TensorListGPU.

as_reshaped_tensor(self: nvidia.dali.backend_impl.TensorListGPU, arg0: List[int]) → nvidia.dali.backend_impl.TensorGPU

Returns a tensor that is a view of this TensorList cast to the given shape.

This function can only be called if TensorList is contiguous in memory and the volumes of requested Tensor and TensorList matches.

as_tensor(self: nvidia.dali.backend_impl.TensorListGPU) → nvidia.dali.backend_impl.TensorGPU

Returns a tensor that is a view of this TensorList.

This function can only be called if is_dense_tensor returns True.

at(self: nvidia.dali.backend_impl.TensorListGPU, arg0: int) → nvidia.dali.backend_impl.TensorGPU

Returns a tensor at given position in the list. Deprecated for __getitem__().

copy_to_external(self: nvidia.dali.backend_impl.TensorListGPU, ptr: object, cuda_stream: object = None, non_blocking: bool = False, use_copy_kernel: bool = False) → None

Copy the contents of this TensorList to an external pointer residing in GPU memory.

This function is used internally by plugins to interface with tensors from supported Deep Learning frameworks.

ptrctypes.c_void_p

Destination of the copy.

cuda_streamctypes.c_void_p

CUDA stream to schedule the copy on (default stream if not provided).

non_blockingbool

Asynchronous copy.

data_ptr(self: nvidia.dali.backend_impl.TensorListGPU) → object

Returns the address of the first element of TensorList.

is_dense_tensor(self: nvidia.dali.backend_impl.TensorListGPU) → bool

Checks whether all tensors in this TensorList have the same shape (and so the list itself can be viewed as a tensor).

For example, if TensorList contains N tensors, each with shape (H,W,C) (with the same values of H, W and C), then the list may be viewed as a tensor of shape (N, H, W, C).

layout(self: nvidia.dali.backend_impl.TensorListGPU) → str

Tensor

TensorCPU

class nvidia.dali.backend.TensorCPU
__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: nvidia.dali.backend_impl.TensorCPU, object: capsule, layout: str = ‘’) -> None

    DLPack of Tensor residing in the CPU memory.

    objectDLPack object

    Python DLPack object

    layoutstr

    Layout of the data

  2. __init__(self: nvidia.dali.backend_impl.TensorCPU, b: buffer, layout: str = ‘’, is_pinned: bool = False) -> None

    Tensor residing in the CPU memory.

    bobject

    the buffer to wrap into the TensorListCPU object

    layoutstr

    Layout of the data

    is_pinnedbool

    If provided memory is page-locked (pinned)

copy_to_external(self: nvidia.dali.backend_impl.TensorCPU, ptr: object) → None

Copy to external pointer in the CPU memory.

ptrctypes.c_void_p

Destination of the copy.

data_ptr(self: nvidia.dali.backend_impl.TensorCPU) → object

Returns the address of the first element of tensor.

dtype(self: nvidia.dali.backend_impl.TensorCPU) → str

String representing NumPy type of the Tensor.

layout(self: nvidia.dali.backend_impl.TensorCPU) → str
shape(self: nvidia.dali.backend_impl.TensorCPU) → list

Shape of the tensor.

squeeze(self: nvidia.dali.backend_impl.TensorCPU) → None

Remove single-dimensional entries from the shape of the Tensor.

TensorGPU

class nvidia.dali.backend.TensorGPU
__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: nvidia.dali.backend_impl.TensorGPU, object: capsule, layout: str = ‘’) -> None

    DLPack of Tensor residing in the GPU memory.

    objectDLPack object

    Python DLPack object

    layoutstr

    Layout of the data

  2. __init__(self: nvidia.dali.backend_impl.TensorGPU, object: object, layout: str = ‘’, device_id: int = -1) -> None

    Tensor residing in the GPU memory.

    objectobject

    Python object that implement CUDA Array Interface

    layoutstr

    Layout of the data

    device_id: int

    Device of where this tensor resides. If not provided, the current device is used.

as_cpu(self: nvidia.dali.backend_impl.TensorGPU) → nvidia.dali.backend_impl.TensorCPU

Returns a TensorCPU object being a copy of this TensorGPU.

copy_to_external(self: nvidia.dali.backend_impl.TensorGPU, ptr: object, cuda_stream: object = None, non_blocking: bool = False, use_copy_kernel: bool = False) → None

Copy to external pointer in the GPU memory.

ptrctypes.c_void_p

Destination of the copy.

cuda_streamctypes.c_void_p

CUDA stream to schedule the copy on (default stream if not provided).

non_blockingbool

Asynchronous copy.

data_ptr(self: nvidia.dali.backend_impl.TensorGPU) → object

Returns the address of the first element of tensor.

dtype(self: nvidia.dali.backend_impl.TensorGPU) → str

String representing NumPy type of the Tensor.

layout(self: nvidia.dali.backend_impl.TensorGPU) → str
shape(self: nvidia.dali.backend_impl.TensorGPU) → list

Shape of the tensor.

squeeze(self: nvidia.dali.backend_impl.TensorGPU) → None

Remove single-dimensional entries from the shape of the Tensor.

Data Layouts

Tensor Layout String format

DALI uses short strings (Python str type) to describe data layout in tensors, by assigning a character to each of the dimensions present in the tensor shape. For example, shape=(400, 300, 3), layout=”HWC” means that the data is an image with 3 interleaved channels, 400 pixels of height and 300 pixels of width.

For TensorLists, the index in the list is not treated as a dimension (the number of sample in the batch) and is not included in the layout.

Interpreting Tensor Layout Strings

DALI allows you to process data of different nature (e.g. image, video, audio, volumetric images) as well as different formats (e.g. RGB image in planar configuration vs. interleaved channels). Typically, DALI operators can deal with different data formats and will behave in different way depending on the nature of the input.

While we do not restrict the valid characters to be used in a tensor layout, DALI operators assume a certain naming convention. Here is a list of commonly used dimension names:

Name

Meaning

H

Height

W

Width

C

Channels

F

Frames

D

Depth

Here are some examples of typically used layouts:

Layout

Description

HWC

Image (interleaved)

CHW

Image (planar)

DHWC

Volumetric Image (interleaved)

CDHW

Volumetric Image (planar)

FHWC

Video

For instance, a crop operation (Crop operator) receiving an input with interleaved layout (“HWC”) will infer that it should crop on the first and second dimensions (H, W). On the other hand, if the input has a planar layout (“CHW”) the crop will take place on the second and third dimensions instead.

Some operators inherently modify the layout of the data (e.g. Transpose), while others propagate the same data layout to the output (e.g. Normalize).

The layout restrictions (if any) for each operator are available through the operator’s documentation.

It is worth to note that the user is responsible to explicitly fill in the layout information when using ExternalSource API.

Constant wrapper

Constant

nvidia.dali.types.Constant(value, dtype=None, shape=None, layout=None, device=None, **kwargs)

Wraps a constant value which can then be used in nvidia.dali.pipeline.Pipeline.define_graph() pipeline definition step.

If the value argument is a scalar and neither shape, layout nor device is provided, the function will return a ScalarConstant wrapper object, which receives special, optimized treatment when used in Arithmetic expressions.

Otherwise, the function creates a dali.ops.Constant node, which produces a batch of constant tensors.

Parameters

  • value (bool, int, float, a list or tuple thereof or a numpy.ndarray) – The constant value to wrap. If it is a scalar, it can be used as scalar value in arithmetic expressions. Otherwise, it will produce a constant tensor node (optionally reshaped according to shape argument). If this argument is is a numpy array, a PyTorch tensor or an MXNet array, the values of shape and dtype will default to value.shape and value.dtype, respectively.

  • dtype (DALIDataType, optional) – Target type of the constant.

  • shape (list or tuple of int, optional) – Requested shape of the output. If value is a scalar, it is broadcast as to fill the requested shape. Otherwise, the number of elements in value must match the volume of the shape.

  • layout (string, optional) – A string descirbing the layout of the constant tensor, e.g. “HWC”

  • device (string, optional, "cpu" or "gpu") – The device to place the constant tensor in. If specified, it forces the value to become a constant tensor node on given device, regardless of value type or shape.

  • **kwargs (additional keyword arguments) – If present, it forces the constant to become a Constant tensor node and the arguments are passed to the dali.ops.Constant operator

class nvidia.dali.types.ScalarConstant(value, dtype=None)

Note

This class should not be instantiated directly; use Constant() function with appropriate arguments to create instances of this class.

Wrapper for a constant value that can be used in DALI Arithmetic expressions and applied element-wise to the results of DALI Operators representing Tensors in nvidia.dali.pipeline.Pipeline.define_graph() step.

ScalarConstant indicates what type should the value be treated as with respect to type promotions. The actual values passed to the backend from python would be int32 for integer values and float32 for floating point values. Python builtin types bool, int and float will be marked to indicate nvidia.dali.types.DALIDataType.BOOL, nvidia.dali.types.DALIDataType.INT32, and nvidia.dali.types.DALIDataType.FLOAT respectively.

Parameters

  • value (bool or int or float) – The constant value to be passed to DALI expression.

  • dtype (DALIDataType, optional) – Target type of the constant to be used in types promotions.

Enums

DALIDataType

class nvidia.dali.types.DALIDataType

Data type of image

Members:

NO_TYPE

UINT8

UINT16

UINT32

UINT64

INT8

INT16

INT32

INT64

FLOAT16

FLOAT

FLOAT64

BOOL

STRING

_BOOL_VEC

_INT32_VEC

_STRING_VEC

_FLOAT_VEC

FEATURE

_FEATURE_VEC

_FEATURE_DICT

IMAGE_TYPE

DATA_TYPE

INTERP_TYPE

TENSOR_LAYOUT

PYTHON_OBJECT

BOOL = DALIDataType.BOOL
DATA_TYPE = DALIDataType.DATA_TYPE
FEATURE = DALIDataType.FEATURE
FLOAT = DALIDataType.FLOAT
FLOAT16 = DALIDataType.FLOAT16
FLOAT64 = DALIDataType.FLOAT64
IMAGE_TYPE = DALIDataType.IMAGE_TYPE
INT16 = DALIDataType.INT16
INT32 = DALIDataType.INT32
INT64 = DALIDataType.INT64
INT8 = DALIDataType.INT8
INTERP_TYPE = DALIDataType.INTERP_TYPE
NO_TYPE = DALIDataType.NO_TYPE
PYTHON_OBJECT = DALIDataType.PYTHON_OBJECT
STRING = DALIDataType.STRING
TENSOR_LAYOUT = DALIDataType.TENSOR_LAYOUT
UINT16 = DALIDataType.UINT16
UINT32 = DALIDataType.UINT32
UINT64 = DALIDataType.UINT64
UINT8 = DALIDataType.UINT8
property name

handle) -> str

Type

(self

DALIIterpType

class nvidia.dali.types.DALIInterpType

Interpolation mode

Members:

INTERP_NN

INTERP_LINEAR

INTERP_CUBIC

INTERP_LANCZOS3

INTERP_TRIANGULAR

INTERP_GAUSSIAN

INTERP_CUBIC = DALIInterpType.INTERP_CUBIC
INTERP_GAUSSIAN = DALIInterpType.INTERP_GAUSSIAN
INTERP_LANCZOS3 = DALIInterpType.INTERP_LANCZOS3
INTERP_LINEAR = DALIInterpType.INTERP_LINEAR
INTERP_NN = DALIInterpType.INTERP_NN
INTERP_TRIANGULAR = DALIInterpType.INTERP_TRIANGULAR
property name

handle) -> str

Type

(self

DALIImageType

class nvidia.dali.types.DALIImageType

Image type

Members:

RGB

BGR

GRAY

YCbCr

ANY_DATA

ANY_DATA = DALIImageType.ANY_DATA
BGR = DALIImageType.BGR
GRAY = DALIImageType.GRAY
RGB = DALIImageType.RGB
YCbCr = DALIImageType.YCbCr
property name

handle) -> str

Type

(self

TensorLayout

class nvidia.dali.types.TensorLayout

PipelineAPIType

class nvidia.dali.types.PipelineAPIType(value)

Pipeline API type

BASIC = 0
ITERATOR = 1
SCHEDULED = 2