Using Custom Camera Tuning Files

Relevant source files

The following files were used as context for generating this wiki page:

• CHANGELOG.md
• examples/tuning_file.py
• picamera2/init.py
• picamera2/picamera2.py
• picamera2/request.py

The picamera2 library provides a powerful mechanism to customize the camera's image processing algorithms (IPA) by loading custom tuning files. These files, formatted in JSON, allow developers to alter default behaviors for algorithms like auto exposure control (AEC), auto white balance (AWB), and more. This gives fine-grained control over the final image output beyond the standard runtime controls.

Tuning files can be applied either during the initialization of the Picamera2 object or loaded and modified dynamically in code before being passed to the camera. This allows for both static, pre-defined camera tuning and dynamic adjustments based on application logic.

Loading a Tuning File

There are two primary methods for applying a custom tuning file: during Picamera2 instantiation or by using a static helper method to load and manipulate the tuning data.

During Picamera2 Initialization

The most direct way to apply a custom tuning is via the tuning parameter in the Picamera2 constructor. This parameter can accept either a string (the filename) or a dictionary object containing the tuning data.

• By Filename (string): When a string is provided, picamera2 sets the LIBCAMERA_RPI_TUNING_FILE environment variable to this path. The underlying libcamera library then uses this file when the camera is initialized.
• By Data (dictionary): When a dictionary is provided, picamera2 writes this data to a temporary JSON file and sets the LIBCAMERA_RPI_TUNING_FILE environment variable to the path of this temporary file. The temporary file is automatically deleted when the Picamera2 object is garbage collected or the program exits.

The following diagram illustrates the initialization process when a tuning file is provided.

This diagram shows the flow for applying a tuning file during Picamera2 initialization.
Sources: picamera2/picamera2.py:313-326, picamera2/picamera2.py:343-344

Using Picamera2.load_tuning_file

picamera2 provides a static method, load_tuning_file, to load a tuning file from disk into a Python dictionary. This is particularly useful when you want to load a default tuning, modify it, and then pass the modified dictionary to the Picamera2 constructor.

@staticmethod
def load_tuning_file(tuning_file, dir=None) -> dict[str, Any]:
    # ...

Sources: picamera2/picamera2.py:228

If the dir parameter is not provided, the method searches for the file in a predefined list of system directories. The search paths depend on the platform (vc4 or pisp).

Default Search Paths

Platform	Search Path
vc4	~/libcamera/src/ipa/rpi/vc4/data
vc4	/usr/local/share/libcamera/ipa/rpi/vc4
vc4	/usr/share/libcamera/ipa/rpi/vc4
pisp	~/libcamera/src/ipa/rpi/pisp/data
pisp	/usr/local/share/libcamera/ipa/rpi/pisp
pisp	/usr/share/libcamera/ipa/rpi/pisp

Sources: picamera2/picamera2.py:237-241

The following flowchart shows the logic for finding and loading the tuning file.

This diagram illustrates the file search and load logic of the load_tuning_file method.
Sources: picamera2/picamera2.py:228-248

Tuning File Structure and Usage

Tuning files are JSON documents that contain configuration for various algorithms. The structure can vary, and picamera2 provides a helper to navigate it.

Accessing Algorithm Parameters

To simplify accessing parameters within a potentially complex tuning file, picamera2 offers the find_tuning_algo static method. This method correctly locates the named algorithm's data regardless of the tuning file version (v1 or v2).

@staticmethod
def find_tuning_algo(tuning, name) -> dict[str, dict]:
    # ...

Sources: picamera2/picamera2.py:251, CHANGELOG.md:278-279

The method checks for a version key in the tuning dictionary. If the version is 2, it searches within an algorithms list; otherwise, it assumes a version 1 flat structure.

Sources: picamera2/picamera2.py:260-263

Example: Modifying AGC Parameters

A common use case is to load a standard tuning file, modify some parameters, and then initialize the camera with the new settings. The examples/tuning_file.py demonstrates this process.

1. Load a default tuning file:

   # Load the default tuning file for the imx477 sensor.
   tuning = Picamera2.load_tuning_file("imx477.json")
   

   Sources: examples/tuning_file.py:11

2. Find and modify an algorithm:
   The rpi.agc algorithm controls auto gain. Here, we find it and adjust the shutter speed range for the "normal" exposure mode.

   # Find the AGC algorithm.
   agc_algo = Picamera2.find_tuning_algo(tuning, "rpi.agc")
   # Set the shutter speed range to 100us - 80ms.
   agc_algo["exposure_modes"]["normal"]["shutter"] = [100, 80000]
   

   Sources: examples/tuning_file.py:12-14

3. Initialize Picamera2 with the modified tuning:
   The modified tuning dictionary is passed directly to the constructor.

   # Pass the modified tuning object to the Picamera2 constructor.
   picam2 = Picamera2(tuning=tuning)
   

   Sources: examples/tuning_file.py:16

Summary

Using custom tuning files in picamera2 allows for deep customization of the image signal processor's behavior. By loading and modifying JSON-based tuning data, developers can override default algorithm parameters to achieve specific imaging results. The library facilitates this through the tuning parameter in the Picamera2 constructor and the load_tuning_file and find_tuning_algo helper methods, providing a flexible and powerful way to control camera output.