anibali / pybraw

Python bindings for the Blackmagic RAW SDK.

PyBraw

Python bindings for the Blackmagic RAW SDK.

Setup

Set up and activate a Conda environment with all required dependencies:

conda env create -f environment.yml
conda activate pybraw

Download the Blackmagic RAW 2.1 SDK for Linux and copy libBlackmagicRawAPI.so into your Conda environment's library path. For example:

sudo cp libBlackmagicRawAPI.so "$CONDA_PREFIX/lib/"

You may also need other libraries depending on your requirements. For example, libDecoderCUDA.so is required for CUDA GPU decoding.

Install the pybraw package:

pip install --no-build-isolation -U .

PyTorch integration

The pybraw.torch module contains a simple interface for reading image frames directly into PyTorch tensors. This works for both CPU and CUDA tensors. Here's some sample code:

from pybraw import PixelFormat, ResolutionScale
from pybraw.torch.reader import FrameImageReader

file_name = 'tests/data/Filmplusgear-skiers-Samnaun-2019-dci-Q5.braw'
# Create a helper for reading video image frames.
reader = FrameImageReader(file_name, processing_device='cuda')
# Get the number of frames in the video.
frame_count = reader.frame_count()

# Prepare the reader.
with reader.run_flow(PixelFormat.RGB_F32_Planar, max_running_tasks=3) as task_manager:
    # Enqueue all tasks. A task specifies a frame index to read, along with other options
    # like the resolution to read it at, the crop region, and the output size.
    tasks = [task_manager.enqueue_task(frame_index, resolution_scale=ResolutionScale.Quarter)
             for frame_index in range(frame_count)]

    for task in tasks:
        # Wait for the task to finish, get its result, and mark it as completed so the next
        # queued task can begin.
        image_tensor = task.consume()
        # Output image info.
        shape = tuple(image_tensor.shape)
        pixel_mean = ','.join([f'{x:.4f}' for x in image_tensor.mean([1, 2])])
        print(f'[Frame {task.frame_index:3d}] shape={shape} pixel_mean={pixel_mean}')

Note that PyTorch is not a hard dependency for this project. If you don't import pybraw.torch, you don't need to have PyTorch installed.

Low-level bindings

Low-level bindings are available in the pybraw._pybraw module. These bindings adhere to the original Blackmagic RAW SDK API closely. Please refer to the official developer manual for more details.

You can use the low-level bindings to do things like read video frames into NumPy arrays with fine-grained control over the Blackmagic RAW SDK functionality. You can take a look at examples/extract_frame.py for a basic example showing how to read frames as PIL images, or examples/manual_flow_cpu.py and examples/manual_flow_gpu.py for more complex manual decoder flow examples.

Tests

In order to run the tests you will need to download the sample BRAW file from https://filmplusgear.com/blackmagic-raw-testfile-3 and move it to tests/data/Filmplusgear-skiers-Samnaun-2019-dci-Q5.braw.

Run the tests using PyTest:

pytest tests

pybraw's Issues

Tests failing, most returning AttributeError: 'NoneType' object has no attribute 'CreateCodec'

I've successfully built and tested this package previously on my local environment consisting of WSL2 Ubuntu. I'm trying to deploy it to an Ubuntu VM in the cloud. I have followed the instructions again but am now unable to run the tests successfully on this VM. Most of the errors returned are AttributeError: 'NoneType' object has no attribute 'CreateCodec' which leads me to think that there's something in my VM's environment that's missing and pybraw isn't able to properly use libBlackmagicRawAPI.so.

Do you have any suggestions?

Also, thanks for putting this package together!