pynari 1.1.2

Python bindings for ANARI

pynari - Python Bindings for ANARI

This project provides a python interface for the Khronos ANARI rendering API. This implementation currently requires a CUDA capable GPU (support for other backends will be added at a later time).

Usage - Quickstart

Assuming you already know how the ANARI API works (and that you have pip-installed this package) you can use ANARI in python as follows: First, import this package

import pynari as anari

(for all the steps below we assume you imported pynari as anari; this is not required, but please take this in mind for the examples below).

Once the package has been imported you can then create a ANARI "device" using

device = anari.newDevice('default')

(where desired, the string passed to 'newDevice' allows for selecting a specific ANARI device, see below; 'default' in this case will currently select a 'barney' backend, see https://github.com/ingowald/barney).

You can then create various ANARI actor objects through creator-methods on that device, such as, for example

world = device.newWorld()
mesh  = device.newGeometry('triangle')
array = device.newArray(anari.FLOAT32_VEC3,vertex)

etc.

Large arrays (such as vertex or index arrays for a triangle mesh) are expected to be populated using numpy, and wrapped in the ANARI 'array' type:

import numpy as np
...
vertex = np.array(...,dtype=np.float32)
mesh.setParameter('vertex.position',anari.ARRAY,
                  device.newArray(anari.FLOAT32_VEC3,vertex));
index  = np.array(...,dtype=np.uint32)
mesh.setParameter('primitive.index',anari.ARRAY,
                  device.newArray(anari.UINT32_VEC3,index));

The ANARI API, and how it is exposed in pynari

For a full description of what ANARI Objects are, what kind of objects exist, and how they work, please refer to the ANARI API Spec at https://registry.khronos.org/ANARI/specs/1.0/ANARI-1.0.html .

Since the official ANARI API is a plain C API we could not implement this literally, but had to make certain changes to make ti more "pythonic". Basically, these rules were applied (we will assume that the pynari module was imported under the alias as anari):

• If there is a C constant/enum of name ANARI_XYZ, it is exposed as anari.XYZ. Example: the C enum of ANARI_FLOAT32 is anari.FLOAT32 in pynari.

• If there is a C API function of anariFunctionXyz(ANARIDevice device, ...) it will be exposed as device.functionXyz(...). Note that in order to remain as close to the C-style API as possible we use CAML-case for function names, not python-casing. I.e., pynari uses device.functionXyz(...), not device.function_xyz(...).

Examples

For a list of several samples, please visit the pynari github repo https://github.com/ingowald/pynari

Supported and Built-in Devices

In ANARI, the 'device' abstraction aims at allowing for what is essentially the concept of a "driver"--i.e., a specific implementation of the hardware for a specific set of underlying hardware, or features. On the OS level, this is realized through installing of different ANARI implementations (e.g., barney or visrtx for CUDA GPUs, or ospray for Intel CPUs and GPUs), and then at runtime selecting one of then by passing a proper 'device name' identifier.

In pynari, we currently expose the device concept as follows:

• If installed through pip, pynari comes with two "baked" devices that are pre-supplied with the pynari pip package, even if no ANARI devices are installed on the OS level: barney_cuda, and barney_cpu (see below).

• the barney_cuda device (shipped with pynari's pip install) is a CUDA- and OptiX accelerated path tracer (see https://github.com/ingowald/barney). barney_cuda requires a OptiX-capable NVIDIA GPU with driver 535 or newer. Specifying device as 'barney_cuda' (or 'gpu' for short) will try to load this device, and throw an exception if this is not possible (eg, if no GPU can be found).

• the barney_cpu device (also shipped with pynari's pip install) is a (much!) slower CPU-only fallback (based on embree) that should produce similar images. barney_cpu does not require an NVIDIA GPU, but will be significantly slower. Specifying barney_cpu (or cpu, for short) will try to load this device, and throw an exception if this did not succeed.

• Specifying device as 'default' first try to load barney_cuda, and use that if possible; if not it will try to load barney_cpu.

• For any device name other than default, barney_cuda, 'gpu', barney_cpu, or 'cpu', pynari will look for a system-installed ANARI implementation, and ask this to create a device of that name.

Issues

For any issues, bugs, or feature requests, please use the github pynari issue tracker.