Camera Handle

class huira.visible8.CameraModelHandle

__init__(*args, **kwargs)

aperture_diameter(self: huira._huira.visible8.CameraModelHandle) → huira._huira.Millimeter

auto_precompute_enabled(self: huira._huira.visible8.CameraModelHandle) → bool

Whether a render builds an out-of-date camera itself. See enable_auto_precompute().

cast_ray(self: huira._huira.visible8.CameraModelHandle, x: float, y: float) → huira::Ray<huira::SpectralBins<8ul, 380, 750> >

Cast a pinhole camera ray, in camera coordinates, through position (x, y) on the image, in the camera’s pixel convention. The position may be outside the image. Raises where the lens distortion has no inverse; see try_cast_ray().

clear_psf(self: huira._huira.visible8.CameraModelHandle) → None

Remove a PSF set with set_measured_psf(): sources are drawn with the aperture’s diffraction pattern again, or without one if it is off.

configure_sensor_from_pitch(self: huira._huira.visible8.CameraModelHandle, resolution: tuple[int, int], pitch_x: object, pitch_y: object = None, cx: float | None = None, cy: float | None = None) → None

Configure sensor using a resolution tuple (width, height) and pixel pitch. pitch_y defaults to pitch_x (square pixels). cx/cy are in the camera’s pixel convention (see set_pixel_convention) and default to the center of the sensor.

configure_sensor_from_size(self: huira._huira.visible8.CameraModelHandle, resolution: tuple[int, int], width: object, height: object = None, cx: float | None = None, cy: float | None = None) → None

Configure sensor using a resolution tuple (width, height) and physical size. height defaults to maintaining square pixels. cx/cy are in the camera’s pixel convention (see set_pixel_convention) and default to the center of the sensor.

defocus_blur_radius(self: huira._huira.visible8.CameraModelHandle, range: object = None) → float

Radius in pixel widths of the defocus blur of a point at ‘range’ along the camera’s axis (any length unit), or of a star (None), as unresolved sources are drawn with it: 0 when it would change no pixel by more than a part in 10^5, and with depth of field off.

defocus_image(self: huira._huira.visible8.CameraModelHandle, radius: int, x_offset: float = 0.0, y_offset: float = 0.0, range: object = None) → huira::Image<huira::SpectralBins<8ul, 380, 750> >

The defocus blur alone of a point at ‘range’ (any length unit; None for a star), in each pixel as psf_image() gives it: a uniform disc of radius defocus_blur_radius(range), or in focus the pixel the point falls in.

delete_distortion(self: huira._huira.visible8.CameraModelHandle) → None

depth_of_field_enabled(self: huira._huira.visible8.CameraModelHandle) → bool

Whether depth of field is on (the default).

describe(self: huira._huira.visible8.CameraModelHandle) → str

A summary of the camera’s settings, one per line, for reading (print(camera) shows it too). The format may change.

diffraction_enabled(self: huira._huira.visible8.CameraModelHandle) → bool

Whether the aperture’s diffraction pattern is on (the default).

diffraction_image(self: huira._huira.visible8.CameraModelHandle, radius: int, x_offset: float = 0.0, y_offset: float = 0.0) → huira::Image<huira::SpectralBins<8ul, 380, 750> >

The aperture’s diffraction pattern alone, in focus, in each pixel as psf_image() gives it, whether or not it is in use.

disable_scatter(self: huira._huira.visible8.CameraModelHandle) → None

Turn scattered light off (the default).

disable_veiling_glare(self: huira._huira.visible8.CameraModelHandle) → None

enable_auto_precompute(self: huira._huira.visible8.CameraModelHandle, auto_precompute: bool = True) → None

Choose what a render does when the camera is out of date: build what it needs and log the time taken (True, the default), or raise (False), which guarantees that no render includes that time.

enable_depth_of_field(self: huira._huira.visible8.CameraModelHandle, depth_of_field: bool = True) → None

Turn depth of field on (the default) or off. On, the camera has the focus set (at infinity unless set): resolved bodies are traced with rays from across the aperture, which blurs whatever is out of focus, and unresolved sources are blurred by the defocus at their depth. Off, everything is in focus, as through a pinhole. Out-of-focus bodies need more samples per pixel to look clean.

enable_diffraction(self: huira._huira.visible8.CameraModelHandle, diffraction: bool = True) → None

Turn the aperture’s diffraction pattern on (the default) or off. On, unresolved sources are drawn with it, averaged over each spectral bin, and resolved bodies are convolved with it; off, a source in focus puts that light in the pixel it falls in. Scattered light and defocus are added either way. A PSF set with set_measured_psf() takes its place while set; clear_psf() goes back to it.

enable_motion_blur(self: huira._huira.visible8.CameraModelHandle, motion_blur: bool = True) → None

Turn motion blur on (the default) or off. On, a SceneView through the camera shows what moves during the exposure blurred along its path, with as many temporal samples as its motion needs, or the number it is given. Off, it renders a still frame, at the middle of the exposure, whatever number it is given.

enable_psf_convolution(self: huira._huira.visible8.CameraModelHandle, convolve_psf: bool = True) → None

Choose whether the PSF and scattered light blur resolved bodies (the path-traced image). On by default. Off, bodies are sharp, and rendering is faster without the whole-image convolution; unresolved sources, such as stars, get the PSF and scattered light either way. Bodies get the whole PSF, across the frame, in focus: path tracing gives them their defocus.

enable_sensor_noise(self: huira._huira.visible8.CameraModelHandle, noise: bool = True) → None

Turn the sensor’s shot noise and read noise on (the default) or off. Off, each pixel collects the expected number of electrons; the dark current’s electrons and the bias are still added, since they are not noise.

focal_length(self: huira._huira.visible8.CameraModelHandle) → huira._huira.Millimeter

focus_diopters(self: huira._huira.visible8.CameraModelHandle) → huira._huira.Diopter

Focus in diopters: the reciprocal of focus_distance(), 0 at infinity.

focus_distance(self: huira._huira.visible8.CameraModelHandle) → huira._huira.Meter

Distance the camera is focused at: negative past infinity, inf at infinity.

focus_sensor_offset(self: huira._huira.visible8.CameraModelHandle) → huira._huira.Micrometer

Focus as the sensor’s offset from the infinity-focus position.

fstop(self: huira._huira.visible8.CameraModelHandle) → float

The f-number: focal length / aperture diameter.

has_set_psf(self: huira._huira.visible8.CameraModelHandle) → bool

Whether a PSF was set in place of the aperture’s diffraction pattern.

in_fov(self: huira._huira.visible8.CameraModelHandle, point: object) → bool

Whether a point in camera coordinates (a huira.Vec3 or three numbers) is in the field of view.

intrinsic_matrix(self: huira._huira.visible8.CameraModelHandle) → numpy.ndarray[numpy.float64]

The camera matrix [[fx, s, cx], [0, fy, cy], [0, 0, 1]] as a 3x3 NumPy array, row by row, as set_intrinsic_matrix() takes it: in pixels, with the principal point in the camera’s pixel convention (see set_pixel_convention).

is_precomputed(self: huira._huira.visible8.CameraModelHandle) → bool

Whether everything the next render needs from the camera is built and up to date.

make_frame_buffer(self: huira._huira.visible8.CameraModelHandle) → huira::FrameBuffer<huira::SpectralBins<8ul, 380, 750> >

motion_blur_enabled(self: huira._huira.visible8.CameraModelHandle) → bool

Whether motion blur is on (the default).

pixel_convention(self: huira._huira.visible8.CameraModelHandle) → huira._huira.PixelConvention

The pixel coordinate convention for the principal point and projected positions.

pixel_pitch(self: huira._huira.visible8.CameraModelHandle) → tuple

The pixel pitch, as a tuple (along x, along y) of Micrometer.

precompute(self: huira._huira.visible8.CameraModelHandle) → None

Build everything the camera needs for the next render now (the tables of its geometry, the PSF’s tables or grid, and the convolution of resolved bodies), so that the time is not spent in the render. Only what is out of date is rebuilt.

project_point(self: huira._huira.visible8.CameraModelHandle, point: object) → tuple

Project a point in camera coordinates (meters; a huira.Vec3 or three numbers) onto the image, as a tuple (x, y) in the camera’s pixel convention.

psf_convolution_enabled(self: huira._huira.visible8.CameraModelHandle) → bool

Whether the PSF and scattered light blur resolved bodies (the default). See enable_psf_convolution().

psf_image(self: huira._huira.visible8.CameraModelHandle, radius: int, x_offset: float = 0.0, y_offset: float = 0.0, range: object = None) → huira::Image<huira::SpectralBins<8ul, 380, 750> >

The light an unresolved source puts in each pixel around it, per channel, as the renderer draws it: the aperture’s diffraction pattern (or a PSF set in its place), with scattered light, blurred by defocus for a source at ‘range’ along the camera’s axis (any length unit; None for a star), and integrated over each pixel, for the source (x_offset, y_offset) pixels from the center pixel’s center. The image is 2 radius + 1 pixels square. Resolved bodies are convolved with it in focus.

resolution(self: huira._huira.visible8.CameraModelHandle) → tuple

The sensor’s resolution, as a tuple (width, height).

scatter_enabled(self: huira._huira.visible8.CameraModelHandle) → bool

Whether scattered light is on.

scatter_image(self: huira._huira.visible8.CameraModelHandle, radius: int, x_offset: float = 0.0, y_offset: float = 0.0) → huira::Image<huira::SpectralBins<8ul, 380, 750> >

The scattered light alone, in focus, in each pixel as psf_image() gives it, holding all of the light rather than its fraction. Raises without scattered light.

sensor_bias_level(self: huira._huira.visible8.CameraModelHandle) → float

The sensor’s bias level, in digital numbers.

sensor_bit_depth(self: huira._huira.visible8.CameraModelHandle) → int

The sensor’s bit depth.

sensor_conversion_gain(self: huira._huira.visible8.CameraModelHandle) → float

The sensor’s conversion gain, in electrons per digital number.

sensor_dark_current(self: huira._huira.visible8.CameraModelHandle) → float

The sensor’s dark current, in electrons per second.

sensor_full_well_capacity(self: huira._huira.visible8.CameraModelHandle) → float

The sensor’s full well capacity, in electrons.

sensor_gain_db(self: huira._huira.visible8.CameraModelHandle) → float

The sensor’s gain, in decibels.

sensor_noise_enabled(self: huira._huira.visible8.CameraModelHandle) → bool

Whether the sensor’s shot noise and read noise are on (the default). See enable_sensor_noise().

sensor_noise_seed(self: huira._huira.visible8.CameraModelHandle) → int

The seed of the sensor’s noise. See set_sensor_noise_seed().

sensor_orientation(self: huira._huira.visible8.CameraModelHandle) → huira._huira.Rotation

The sensor’s orientation relative to the camera, as a huira.Rotation from the sensor’s axes (in which projections and rays are given) to the camera’s: the roll about the optical axis.

sensor_quantum_efficiency(self: huira._huira.visible8.CameraModelHandle) → huira._huira.visible8.SpectralBins

The sensor’s quantum efficiency, per spectral bin.

sensor_read_noise(self: huira._huira.visible8.CameraModelHandle) → float

The sensor’s read noise, in electrons.

sensor_roll(self: huira._huira.visible8.CameraModelHandle) → huira._huira.Radian

The sensor’s roll about the optical axis, in Radian. See set_sensor_roll().

sensor_unity_db(self: huira._huira.visible8.CameraModelHandle) → float

The gain, in decibels, at which the sensor’s conversion gain is unity.

set_aperture_diameter(self: huira._huira.visible8.CameraModelHandle, diameter: object) → None

Set the aperture’s diameter (any distance unit). It is kept if the focal length changes, so the f-number follows the focal length.

set_brown_conrady_distortion(self: huira._huira.visible8.CameraModelHandle, coeffs: huira._huira.BrownCoefficients) → None

set_focal_length(self: huira._huira.visible8.CameraModelHandle, focal_length: object) → None

Set the focal length (accepts any distance unit). Until the aperture is set, the camera stays f/2.8. After set_fstop() the aperture’s diameter is kept, so the f-number changes (with a warning); set the f-stop after the focal length.

set_focus_diopters(self: huira._huira.visible8.CameraModelHandle, diopters: object) → None

Focus in diopters, the reciprocal of the focus distance (Diopter). 0 focuses at infinity; negative values focus past infinity.

set_focus_distance(self: huira._huira.visible8.CameraModelHandle, focus_distance: object) → None

Focus at a distance (any distance unit). Negative values focus past infinity; infinity focuses at infinity.

set_focus_sensor_offset(self: huira._huira.visible8.CameraModelHandle, offset: object) → None

Focus by moving the sensor from the infinity-focus position (any distance unit). 0 focuses at infinity, positive values (sensor farther from the lens) focus in front of the camera, negative values focus past infinity. The offset, not the focus distance, is kept fixed if the focal length changes.

set_fstop(self: huira._huira.visible8.CameraModelHandle, fstop: float) → None

Set the f-number, e.g. 8 for f/8. This sets the aperture’s diameter from the current focal length, and the diameter is what is kept if the focal length changes later (with a warning), so set the f-stop after the focal length. Until the aperture is set, the camera is f/2.8 at any focal length.

set_intrinsic_matrix(*args, **kwargs)

Overloaded function.

1. set_intrinsic_matrix(self: huira._huira.visible8.CameraModelHandle, intrinsic_matrix: huira._huira.Mat3, resolution: tuple[int, int], anchor_focal_length: object) -> None

Set the intrinsics from a huira.Mat3 camera matrix [[fx, s, cx], [0, fy, cy], [0, 0, 1]] (up to scale), with a resolution tuple and physical focal length anchor. The principal point is in the camera’s pixel convention (see set_pixel_convention).

2. set_intrinsic_matrix(self: huira._huira.visible8.CameraModelHandle, intrinsic_matrix: numpy.ndarray[numpy.float64], resolution: tuple[int, int], anchor_focal_length: object) -> None

Set the intrinsics from a 3x3 camera matrix, as a NumPy array or nested list written row by row: [[fx, s, cx], [0, fy, cy], [0, 0, 1]] (up to scale), where s is the skew. The principal point is in the camera’s pixel convention (see set_pixel_convention).

set_intrinsics(self: huira._huira.visible8.CameraModelHandle, fx: float, fy: float, cx: float, cy: float, resolution: tuple[int, int], anchor_focal_length: object, skew: float = 0.0) → None

Explicitly set mathematical intrinsics with a resolution tuple and physical focal length anchor: (x, y) projects to (fx * x + skew * y + cx, fy * y + cy). cx/cy are in the camera’s pixel convention (see set_pixel_convention); skew is 0 for perpendicular pixel axes.

set_measured_psf(self: huira._huira.visible8.CameraModelHandle, data: huira::Image<huira::SpectralBins<8ul, 380, 750> >, samples_per_pixel: float, sampling: huira._huira.PSFSampling, focus: huira._huira.PSFFocus = <PSFFocus.InFocus: 0>) → None

Use a measured (user-supplied) PSF in place of the aperture’s diffraction pattern, until clear_psf(). ‘data’ is an Image of centered PSF samples, taken whole: as holding all of a source’s light out to its farthest sample (crop it to use less); ‘samples_per_pixel’ is the measurement sampling density per sensor pixel per axis; ‘sampling’ says what the samples are (see PSFSampling): PSFSampling.PixelIntegrated if the data came from the sensor being simulated, such as a star’s image, and otherwise almost always PSFSampling.PointSampled, such as optical design software’s PSF. Sources are drawn from the spline through the samples. ‘focus’ says whether it is a point’s in focus, which the camera’s focus blurs (the default), or already holds the camera’s defocus (see PSFFocus). Scattered light, if set, is added to it.

set_opencv_distortion(self: huira._huira.visible8.CameraModelHandle, coeffs: huira._huira.OpenCVCoefficients) → None

set_owen_distortion(self: huira._huira.visible8.CameraModelHandle, coeffs: huira._huira.OwenCoefficients) → None

set_pixel_convention(self: huira._huira.visible8.CameraModelHandle, convention: huira._huira.PixelConvention) → None

Set the pixel coordinate convention for the principal point (cx, cy) and projected positions, e.g. huira.PixelConvention.fits(). The default is huira.PixelConvention.opencv(): the top-left pixel’s center is (0, 0), y down. May be set before or after the principal point; changes nothing rendered unless a principal point was given.

set_scatter(self: huira._huira.visible8.CameraModelHandle, fraction: float, slope: float, shoulder_angle: object, outer_angle: object = None) → None

Set scattered light in angles (any angle unit, e.g. Arcsecond): ‘fraction’ of each source’s light spreads as (1 + (theta / shoulder_angle)^2)^(-slope / 2), falling as theta^-(slope + 2) beyond ‘outer_angle’. A slope of 2 or less needs an outer angle. It is added to diffraction or a PSF that was set, and included in psf_image(); scatter_image() gives it alone.

set_sensor_bias_level(self: huira._huira.visible8.CameraModelHandle, bias_level: float) → None

set_sensor_bit_depth(self: huira._huira.visible8.CameraModelHandle, bit_depth: int) → None

set_sensor_conversion_gain(self: huira._huira.visible8.CameraModelHandle, gain: float) → None

set_sensor_dark_current(self: huira._huira.visible8.CameraModelHandle, dark_current: float) → None

set_sensor_full_well_capacity(self: huira._huira.visible8.CameraModelHandle, fwc: float) → None

set_sensor_gain_db(self: huira._huira.visible8.CameraModelHandle, gain_db: float) → None

set_sensor_noise_seed(self: huira._huira.visible8.CameraModelHandle, seed: int) → None

Seed the sensor’s noise. Setting the same seed again repeats the same sequence of frames; sensors get distinct seeds by default.

set_sensor_quantum_efficiency(*args, **kwargs)

Overloaded function.

1. set_sensor_quantum_efficiency(self: huira._huira.visible8.CameraModelHandle, qe: float) -> None

Set quantum efficiency (scalar, e.g. 0.7)

2. set_sensor_quantum_efficiency(self: huira._huira.visible8.CameraModelHandle, qe: huira._huira.visible8.SpectralBins) -> None

Set quantum efficiency (spectral)

set_sensor_read_noise(self: huira._huira.visible8.CameraModelHandle, read_noise: float) → None

set_sensor_roll(self: huira._huira.visible8.CameraModelHandle, angle: object) → None

Set the sensor’s roll about the optical axis (any angle unit, e.g. Degree). The sensor’s x axis is turned by the angle toward its y axis, so with OpenCV’s axes (the default) a positive roll turns the scene counterclockwise in the image. The camera’s pose is unchanged; projections and rays are in the sensor’s axes.

set_sensor_unity_db(self: huira._huira.visible8.CameraModelHandle, unity_db: float) → None

set_veiling_glare(self: huira._huira.visible8.CameraModelHandle, alpha: float) → None

Redistribute the given fraction of total collected energy uniformly across the image (veiling glare).

try_cast_ray(self: huira._huira.visible8.CameraModelHandle, x: float, y: float) → object

As cast_ray(), but None where the lens distortion has no inverse, rather than raising.

try_project_point(self: huira._huira.visible8.CameraModelHandle, point: object) → tuple

As project_point(), but (nan, nan) for a point outside the field of view.

use_blender_convention(self: huira._huira.visible8.CameraModelHandle, value: bool = True) → None

Use Blender’s camera convention (-z forward, y up) rather than OpenCV’s (z forward, y down, the default).

uses_blender_convention(self: huira._huira.visible8.CameraModelHandle) → bool

Whether the camera uses Blender’s convention (-z forward, y up).

valid(self: huira._huira.visible8.CameraModelHandle) → bool