circle-of-confusion 0.2.5

Calculator for Circle of Confusion (CoC) to calculate the size in pixels of an area, used for depth of field processing.

Circle of Confusion

Calculator for Circle of Confusion (CoC) to calculate the size in pixels of an area, used for depth of field processing.

It's built in Rust and compiled to Web Assembly (wasm32) for non-rust targets.

In Rust to use the library in no-std: enable the no-std feature. Add the project to your Cargo.toml by using

cargo add circle-of-confusion

# or for no-std:
cargo add circle-of-confusion --features no-std

Or in your Python project with a wasmtime runtime:

pip install circle-of-confusion[recommended]

The wasmtime runtime is recommended by default, but is not supported on every platform. So as a fallback when no features are specified, it used pywasm to support any platform starting from Python 3.11. For 3.10 and 3.9 wasmtime is still necessary.

To build yourself, you need to have protoc installed and Rust. For wasm packages you need to have the wasm32-unknown-unknown target installed.

It is not made compatible with Windows, but you can build it in a Linux based container.

Usage

The calculator is able to calculate the Circle of Confusion based on the provided settings. The size in px is the radius of the convolution. A CoC of 10 would mean a diameter of 20 pixels.

Output:

• + is for far field pixels
• - is for near field pixels

Modes

The calculator supports two modes, one is physically accurate, the other lets you tune your own DoF size.

Manually

When no camera data is provided to the Settings struct (just give the parameter a None), the manual mode will be used. This creates a smooth falloff to the focal plane point, based on the size and max size added. It will gradually apply the size based on the distance from the focal plane. When using a larger size, the CoC will be increased. Protect can be used to apply a safe region to the focal plane.

Camera

When the camera data is applied to the settings, the camera values will be used instead. This matches real world CoC values. Lowering f-stop will increase the CoC values, just like increasing the focal-length would. This calculation is based on the CoC algorithm: Wikipedia

Examples

It's really simple to use, you need to assemble the settings to calculate the circle of confusion. The interface identical (besides the obvious syntax differences) for Rust and Python. For example for camera based calculations:

Python

from circle_of_confusion import (
    Calculator,
    calculate,
    Settings,
    Math,
    CameraData,
    WorldUnit,
    Resolution,
    Filmback,
)

camera_data = CameraData(
    focal_length=100.0,
    f_stop=2.0,
    filmback=Filmback(width=24.576, height=18.672),
    near_field=0.1,
    far_field=10000.0,
    world_unit=WorldUnit.M,
    resolution=Resolution(width=1920, height=1080),
)
settings = Settings(
    size=10.0,
    max_size=100.0,
    math=Math.REAL,
    focal_plane=30.0,
    protect=0.0,
    pixel_aspect=1.0,
    camera_data=camera_data,
)
calculator = Calculator(settings)
result = calculate(calculator, 10.0)  # input distance value from Z-depth
assert result == -11.93532943725586

Rust

use circle_of_confusion::{Calculator, Settings, Math, CameraData, WorldUnit, Filmback, Resolution};

fn main() {
    let camera_data = CameraData {
        focal_length: 100.0,
        f_stop: 2.0,
        filmback: Filmback { width: 24.576, height: 18.672 },
        near_field: 0.1,
        far_field: 10000.0,
        world_unit: WorldUnit::M.into(),
        resolution: Resolution { width: 1920, height: 1080 },
    };
    let settings = Settings {
        size: 10.0,
        max_size: 100.0,
        math: Math::Real.into(),
        focal_plane: 30.0,
        protect: 0.0,
        pixel_aspect: 1.0,
        camera_data: Some(camera_data),
    };
    let calculator = Calculator::new(settings);
    let result = calculator.calculate(10.0); // input distance value from Z-depth
    assert_eq!(result, -11.935329);
}