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


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
-
output Caller-owned writable stream; caller handles flush/sync/close. frame Immutable combined frame, or packed YUYV when evidence selects LWIR_YUYV_IMAGE. bytes Exact frame size. width Native width. height Native height. synthetic Whether thermal evidence is simulated. evidence Optional capture provenance; required for display orientation. render Optional 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
-
path File 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
-
path New destination, never an existing file. frame Immutable combined frame. bytes Exact combined size. width Native width. height Native height. synthetic Select 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
-
path New destination, never an existing file. frame Immutable combined frame or image-only YUYV. bytes Exact byte count for the selected layout. width Native width. height Native height. synthetic True for simulated rather than live evidence. evidence Optional 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
-
path New destination, never an existing file. frame Immutable native frame. bytes Exact frame byte count for its layout. width Native width before orientation. height Native height before orientation. synthetic True for simulated rather than live evidence. evidence Optional capture record, required when orientation changes. render Display 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
-
path New raw destination. frame Immutable combined frame. bytes Exact combined size. width Native width. height Native 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.