Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
imx500::Camera Class Reference

One exclusive IMX500 owner with bounded reusable YUV420 buffers. More...

#include <imx500_camera.hpp>

Data Structures

struct  Impl
 Capture resources and the callback-to-owner handoff, not model results. More...

Public Member Functions

 Camera ()
 Construct unopened camera state; construction does not acquire the sensor.
 ~Camera ()
 Stop streaming before freeing requests/buffers and releasing the camera.
 Camera (const Camera &)=delete
 Camera owners cannot be copied.
Camera & operator= (const Camera &)=delete
 Assignment cannot replace an acquired sensor owner.
void open (const char *model, unsigned width=2028, unsigned height=1520, bool photo_only=false)
 Acquire one eligible camera and configure bounded capture, uploading an RPK only when requested.
FrameLease capture ()
 Lease a fresh post-request exposure and its own tensor metadata.
bool save (const FrameLease &frame, const char *filename, const FrameProcessor &processor)
 Map a leased frame and publish its JPEG plus available evidence.
bool with_pixels (const FrameLease &frame, bool(*visitor)(const FrameView &, const std::array< const uint8_t *, 3 > &, unsigned, void *), void *context)
 Grant scoped CPU pixel access without transferring DMA/frame ownership.

Private Attributes

std::unique_ptr< Impl > impl_

Detailed Description

One exclusive IMX500 owner with bounded reusable YUV420 buffers.

Precondition
Control operations and lease destruction are serialized by their owner; the camera's callback thread is synchronized internally.

Definition at line 157 of file imx500_camera.hpp.

Constructor & Destructor Documentation

◆ Camera() [1/2]

imx500::Camera::Camera ( )

Construct unopened camera state; construction does not acquire the sensor.

Allocate unopened camera state; discovery and acquisition wait for open().

Definition at line 539 of file imx500_camera.cpp.

◆ ~Camera()

imx500::Camera::~Camera ( )
default

Stop streaming before freeing requests/buffers and releasing the camera.

Stop callbacks, free requests/buffers, then release the camera.

Precondition
Every frame lease has already been destroyed.
All leases and pixel visitors have finished; they borrow this state.

◆ Camera() [2/2]

imx500::Camera::Camera ( const Camera & )
delete

Camera owners cannot be copied.

Member Function Documentation

◆ capture()

FrameLease imx500::Camera::capture ( )

Lease a fresh post-request exposure and its own tensor metadata.

Returns
Move-only lease; destroy it before the next capture or camera shutdown.
Exceptions
std::runtime_errorfor missing startup, a still-live prior lease, queue failure, unavailable clock or frame timeout.

Freshness uses the sensor/BOOTTIME domain, not JPEG download time. Model-specific validation remains the processor's responsibility.

A queued frame can predate a SHOT command. Compare sensor timestamps in the BOOTTIME domain instead of treating callback arrival as exposure time. Tensor validity and interpretation remain the application's responsibility.

Definition at line 642 of file imx500_camera.cpp.

◆ open()

void imx500::Camera::open ( const char * model,
unsigned width = 2028,
unsigned height = 1520,
bool photo_only = false )

Acquire one eligible camera and configure bounded capture, uploading an RPK only when requested.

Parameters
modelReadable RPK for IMX500 inference, or NULL for plain pixels.
widthRequested JPEG width, not model-input width.
heightRequested JPEG height, not model-input height.
photo_onlySelect IMX500 image-only capture and leave frame duration to libcamera.
Exceptions
std::runtime_errorfor unavailable/ambiguous hardware or rejected configuration.

Configuration adjustments that change our expected geometry, YUV420 layout or buffer budget are rejected rather than silently changing downstream assumptions.

Exactly one eligible camera is required so discovery order cannot silently choose a different sensor. Partial startup remains owned by Impl and is unwound when the Camera is destroyed.

Definition at line 547 of file imx500_camera.cpp.

◆ operator=()

Camera & imx500::Camera::operator= ( const Camera & )
delete

Assignment cannot replace an acquired sensor owner.

◆ save()

bool imx500::Camera::save ( const FrameLease & frame,
const char * filename,
const FrameProcessor & processor )

Map a leased frame and publish its JPEG plus available evidence.

Parameters
frameLease obtained from this camera, still alive and unmoved.
filenameNew absolute JPEG destination; existing images are not overwritten.
processorApplication-owned sidecar policy for this same exposure.
Returns
True after JPEG publication, false for rejected layout/path or write failure.

Mapping is scoped separately from the lease: CPU DMA ownership ends before the request can be recycled. Missing analysis does not discard good pixels.

Warning
Success is not proof of a useful neural match, geolocation accuracy, complete multi-file crash atomicity or parent-directory power-loss durability.

with_pixels() scopes CPU/DMA access around publication; the caller still owns the frame lease and decides when the request returns to the queue.

Exceptions
std::exceptionMapping, filesystem or processor failures may propagate.

Definition at line 771 of file imx500_camera.cpp.

◆ with_pixels()

bool imx500::Camera::with_pixels ( const FrameLease & frame,
bool(* visitor )(const FrameView &, const std::array< const uint8_t *, 3 > &, unsigned, void *),
void * context )

Grant scoped CPU pixel access without transferring DMA/frame ownership.

Parameters
frameLive lease acquired from this camera.
visitorCallback consuming validated YUV420 planes and stride before mappings are released.
contextBorrowed callback state, not retained by the camera.
Returns
Callback result, or false for invalid ownership/layout/visitor.
Precondition
The visitor must not retain pixel pointers or release the lease during the call.

Prepare a model-sized tensor here, then release the lease before expensive inference.

Plane allocation sizes alone do not prove that a frame produced enough bytes. Check bytesused before exposing chroma, and unmap/end CPU access before returning or unwinding to the code that can recycle the request.

Exceptions
std::exceptionDMA/mapping failures and visitor exceptions may propagate.

Definition at line 785 of file imx500_camera.cpp.

Field Documentation

◆ impl_

std::unique_ptr<Impl> imx500::Camera::impl_
private

Camera/request implementation hidden from model-specific callers. One owned capture state; libcamera has its own allocation policy.

Definition at line 209 of file imx500_camera.hpp.


The documentation for this class was generated from the following files: