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
lwir_image.h File Reference

JPEG encoding and durable no-overwrite publication of LWIR frames. More...

#include "lwir_frame.h"
#include "sensor_capture.h"
#include "lwir_state.h"
#include <stdio.h>
Include dependency graph for lwir_image.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  lwir_evidence
 Borrowed provenance for one publication; strings must outlive encoding. More...

Functions

bool lwir_encode_jpeg (FILE *output, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic, const struct lwir_evidence *evidence, const struct lwir_render_options *render)
 Encode into an existing stream without owning its publication policy.
const char * lwir_jpeg_provider (void)
 Identify the compiled codec provider for diagnostics and benchmark logs.
bool lwir_remove_published (const char *path)
 Remove a file previously published by this process and sync its directory.
bool lwir_write_jpeg (const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic)
 Publish a sensor-view JPEG with exact native thermal markers.
bool lwir_write_jpeg_evidence (const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic, const struct lwir_evidence *evidence)
 Publish the sensor view plus borrowed capture provenance.
bool lwir_write_raw (const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height)
 Publish an exact combined frame with the same no-overwrite contract.
bool lwir_write_jpeg_rendered (const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic, const struct lwir_evidence *evidence, const struct lwir_render_options *render)
 Publish a rendered view without altering original temperature samples.

Detailed Description

JPEG encoding and durable no-overwrite publication of LWIR frames.

Final stage of the LWIR capture pipeline. Acquisition and frame arithmetic (lwir_frame.h) yield an immutable frame, the renderer (lwir_render.h) converts it into display rows, and this module wraps those rows in a JPEG together with the evidence needed to interpret it later. Frame arithmetic never depends on this module.

Input frames:

  • Combined (LWIR_COMBINED): packed YUYV display plane followed by an equally sized little-endian Kelvin*64 temperature plane; see lwir_frame_bytes().
  • Image-only (LWIR_YUYV_IMAGE, TDK device): the limited-range YUYV plane alone, half the combined size, with no temperatures.

JPEG output, produced by the bundled IJG libjpeg 9f (lwir_jpeg_provider()):

  • APP14 "LWIREV02" key=value provenance text, when evidence is supplied.
  • APP1 EXIF holding the sensor-capture record, for live frames only.
  • APP15 chunks carrying the exact native temperature plane, signed "LWIRRAW1" (live) or "LWIRSIM1" (synthetic replay); see lwir_container.h.
  • Sequential scan, 4:4:4 sampling, quality 1..100 (0 means legacy 100).

Invariants:

  • Temperatures survive bit-exact at any JPEG quality; only the display is lossy.
  • Image-only frames carry no thermal markers and are expanded from limited to full-range YCbCr before encoding.
  • Publication never replaces an existing path and is durable on success.
  • Encoding uses one static workspace: single-threaded and not re-entrant.

Definition in file lwir_image.h.

Function Documentation

◆ lwir_encode_jpeg()

bool lwir_encode_jpeg ( FILE * output,
const uint8_t * frame,
size_t bytes,
unsigned width,
unsigned height,
bool synthetic,
const struct lwir_evidence * evidence,
const struct lwir_render_options * render )

Encode into an existing stream without owning its publication policy.

Parameters
outputCaller-owned writable stream; caller handles flush/sync/close.
frameImmutable combined frame, or packed YUYV when evidence selects LWIR_YUYV_IMAGE.
bytesExact frame size.
widthNative width.
heightNative height.
syntheticWhether thermal evidence is simulated.
evidenceOptional capture provenance; required for display orientation.
renderOptional display policy; NULL keeps the sensor image.
Returns
True on successful encoding. Discard partial output on failure.

Serial encoder, bounded scanline workspace. The codec may allocate internally. Image-only evidence permits sensor-view rendering only, expands limited-range YUYV for JPEG, and emits no thermal markers. Otherwise JPEG display is lossy; embedded native temperatures are exact.

Failures set errno: EINVAL for bad arguments, quality above 100 or display orientation without evidence; ENOTSUP for image-only frames combined with thermal rendering, synthetic output or thermal evidence; ENOSPC when the provenance text does not fit its fixed buffer; EIO for codec failures. Renderer failures keep the renderer's errno.

Note
A NULL render, or jpeg_quality 0, encodes at the legacy quality 100.
Warning
Uses process-wide static encoder state: never call concurrently or from a signal handler.

Encode into an existing stream without owning its publication policy.

Image-only frames are half the combined size. Layout values beyond the known enum are rejected rather than guessed. A NULL render becomes the plain sensor view with quality 0, i.e. legacy 100.

Definition at line 390 of file lwir_image.c.

◆ lwir_jpeg_provider()

const char * lwir_jpeg_provider ( void )

Identify the compiled codec provider for diagnostics and benchmark logs.

Returns
Static string "ijg-9f" (bundled IJG libjpeg 9f); never NULL, never freed.

Identify the compiled codec provider for diagnostics and benchmark logs.

Definition at line 380 of file lwir_image.c.

◆ lwir_remove_published()

bool lwir_remove_published ( const char * path)

Remove a file previously published by this process and sync its directory.

Parameters
pathFile name returned as published by one of the writers below.
Returns
True when the name was removed and the removal persisted; errno otherwise.

Used to undo a raw companion when the matching JPEG could not be published, so a failed capture leaves neither file behind.

Warning
Only pass names this process published; it removes whatever the path names.

Remove a file previously published by this process and sync its directory.

Definition at line 488 of file lwir_image.c.

◆ lwir_write_jpeg()

bool lwir_write_jpeg ( const char * path,
const uint8_t * frame,
size_t bytes,
unsigned width,
unsigned height,
bool synthetic )

Publish a sensor-view JPEG with exact native thermal markers.

Parameters
pathNew destination, never an existing file.
frameImmutable combined frame.
bytesExact combined size.
widthNative width.
heightNative height.
syntheticSelect simulated versus live thermal evidence.
Returns
True after exclusive publication and directory sync. On failure errno holds the first error; EEXIST means the destination already existed.

Writes a private temporary "PATH.part.XXXXXX", syncs it, then hard-links it to path so the name appears atomically and only when complete. Without evidence no APP14/EXIF is written, but the thermal markers still are.

Warning
A failure after linking may leave a final file. Inspect; never auto-retry.

Publish a sensor-view JPEG with exact native thermal markers.

Definition at line 501 of file lwir_image.c.

◆ lwir_write_jpeg_evidence()

bool lwir_write_jpeg_evidence ( const char * path,
const uint8_t * frame,
size_t bytes,
unsigned width,
unsigned height,
bool synthetic,
const struct lwir_evidence * evidence )

Publish the sensor view plus borrowed capture provenance.

Parameters
pathNew destination, never an existing file.
frameImmutable combined frame or image-only YUYV.
bytesExact byte count for the selected layout.
widthNative width.
heightNative height.
syntheticTrue for simulated rather than live evidence.
evidenceOptional capture record; simulated output strips live state.
Returns
True after exclusive publication and directory sync.

Uses the same temporary-file and no-overwrite publication contract as lwir_write_jpeg().

Warning
A failure after linking may leave a final file; inspect before retrying.
Note
Image-only evidence (LWIR_YUYV_IMAGE) expects the half-size YUYV frame.

Publish the sensor view plus borrowed capture provenance.

Definition at line 508 of file lwir_image.c.

◆ lwir_write_jpeg_rendered()

bool lwir_write_jpeg_rendered ( const char * path,
const uint8_t * frame,
size_t bytes,
unsigned width,
unsigned height,
bool synthetic,
const struct lwir_evidence * evidence,
const struct lwir_render_options * render )

Publish a rendered view without altering original temperature samples.

Parameters
pathNew destination, never an existing file.
frameImmutable native frame.
bytesExact frame byte count for its layout.
widthNative width before orientation.
heightNative height before orientation.
syntheticTrue for simulated rather than live evidence.
evidenceOptional capture record, required when orientation changes.
renderDisplay policy; orientation requires evidence for its native mapping.
Returns
True after exclusive publication and directory sync.

Use the same no-overwrite publication as lwir_write_jpeg_evidence().

Warning
A failure after linking may leave a final file; inspect before retrying.
Note
Rendering changes only display pixels; the APP15 temperature plane is always the unmodified native data.

Publish a rendered view without altering original temperature samples.

Definition at line 522 of file lwir_image.c.

◆ lwir_write_raw()

bool lwir_write_raw ( const char * path,
const uint8_t * frame,
size_t bytes,
unsigned width,
unsigned height )

Publish an exact combined frame with the same no-overwrite contract.

Parameters
pathNew raw destination.
frameImmutable combined frame.
bytesExact combined size.
widthNative width.
heightNative height.
Returns
True after publication; ambiguous failures must not be retried blindly.

Bytes are written verbatim through the same temporary/link/sync sequence as the JPEG writers, so the companion is equally durable and never overwrites. Always expects the full combined size.

Publish an exact combined frame with the same no-overwrite contract.

Definition at line 516 of file lwir_image.c.