LWIR JPEG encoder and durable no-overwrite file publisher. More...
#include "lwir_image.h"#include "lwir_container.h"#include "exifite.h"#include "lwir_render.h"#include <errno.h>#include <fcntl.h>#include <limits.h>#include <setjmp.h>#include <stdio.h>#include <stdlib.h>#include <string.h>#include <unistd.h>#include <jpeglib.h>
Go to the source code of this file.
Functions | |
| static void | write_u32 (uint8_t *destination, uint32_t value) |
Store value as four little-endian bytes. | |
| static void | jpeg_failure (j_common_ptr encoder) |
| libjpeg error_exit replacement: abandon the photo instead of exiting. | |
| static int | write_provenance_markers (j_compress_ptr encoder, unsigned width, unsigned height, unsigned display_width, unsigned display_height, bool synthetic, const struct lwir_evidence *evidence, const struct lwir_render_options *render, const struct lwir_render_range *range) |
| Write application provenance without taking ownership of the encoder. | |
| static void | write_thermal_markers (j_compress_ptr encoder, const uint8_t *frame, unsigned width, unsigned height, bool synthetic) |
| Preserve exact native temperatures independently of display rendering. | |
| static uint8_t | expand_video_component (uint8_t value, unsigned low, unsigned span) |
| Expand one limited-range video component to full range. | |
| static bool | 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) |
| Own the serial codec lifecycle and the ordered marker/scanline stages. | |
| static int | open_parent (const char *path) |
Open the directory that will contain path, for fsync after linking. | |
| const char * | lwir_jpeg_provider (void) |
| Report the bundled codec; see lwir_image.h. | |
| 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) |
| Validate the frame size for its layout, then encode; see lwir_image.h. | |
| static bool | publish (const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic, bool raw, const struct lwir_evidence *evidence, const struct lwir_render_options *render) |
| Durably publish a JPEG or raw companion under a new name. | |
| bool | lwir_remove_published (const char *path) |
| Remove a file this process published and persist the removal; see lwir_image.h. | |
| bool | lwir_write_jpeg (const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height, bool synthetic) |
| Publish the sensor view without evidence; see lwir_image.h. | |
| 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 with provenance; see lwir_image.h. | |
| bool | lwir_write_raw (const char *path, const uint8_t *frame, size_t bytes, unsigned width, unsigned height) |
| Publish the combined frame verbatim; see lwir_image.h. | |
| 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 with provenance; see lwir_image.h. | |
Variables | |
| struct { | |
| struct jpeg_compress_struct encoder | |
| struct jpeg_error_mgr error | |
| jmp_buf recovery | |
| uint8_t marker [LWIR_THERMAL_HEADER_BYTES+LWIR_THERMAL_CHUNK_CAPACITY] | |
| uint8_t row [LWIR_MAX_WIDTH *3U] | |
| struct exif_document exif | |
| uint8_t exif_payload [EXIF_MAX_PAYLOAD] | |
| char evidence [8192] | |
| } | jpeg_workspace |
| Static encoder state shared by every photo. | |
Detailed Description
LWIR JPEG encoder and durable no-overwrite file publisher.
Implements lwir_image.h. Every photo goes through one static libjpeg workspace so no heap allocation is made per photo by this module (libjpeg still allocates internally). Consequently the encoder is single-threaded and not re-entrant.
Marker order inside each JPEG, all before the first scanline:
- APP14 "LWIREV02" provenance text (only with evidence).
- APP1 EXIF with the sensor-capture tag (only with evidence, live frames).
- APP15 thermal chunks (combined frames only). libjpeg may emit its own JFIF APP0 before these, so readers must scan markers rather than expect APP1 directly after SOI.
Codec errors longjmp from jpeg_failure() back to encode_jpeg() with errno = EIO. Publication writes a temporary, fsyncs, link()s and fsyncs the directory; see publish().
Definition in file lwir_image.c.
Function Documentation
◆ encode_jpeg()
|
static |
Own the serial codec lifecycle and the ordered marker/scanline stages.
- Parameters
-
output Caller-owned stream; flush/sync/close remain with the caller. frame Frame already size-checked by lwir_encode_jpeg(). bytes Exact frame size. width Native width. height Native height. synthetic True for replayed/simulated frames. evidence Optional provenance; required for any display orientation. render Display policy (never NULL here).
- Returns
- True when the full JPEG was handed to the stream. On false, errno is EINVAL, ENOTSUP, ENOSPC, EIO, or the renderer's errno; discard the output.
Validates the image-only and orientation rules before touching the codec, writes markers, then renders and compresses one row at a time so the only image buffer is the single-row workspace.
Definition at line 276 of file lwir_image.c.
◆ expand_video_component()
|
static |
Expand one limited-range video component to full range.
- Parameters
-
value Component sample from the limited-range source. low Lowest legal code (16 for luma). span Legal code span: 219 for luma (16..235), 224 for chroma (16..240).
- Returns
- Full-range 0..255 component.
JPEG/JFIF assumes full-range YCbCr, so passing TDK video through unchanged would look washed out. Out-of-range inputs clamp. Chroma scales symmetrically around the neutral 128 and truncates toward zero; luma rounds.
- Note
- The chroma branch is selected by span == 224 and ignores
low, implicitly assuming low == 16.
Definition at line 253 of file lwir_image.c.
◆ jpeg_failure()
|
static |
libjpeg error_exit replacement: abandon the photo instead of exiting.
- Parameters
-
encoder Unused; the single static workspace already identifies the photo.
- Note
- Does not return; jumps to the recovery point armed by the encoder.
The default handler calls exit(), which would kill the capture worker. errno is set to EIO before jumping so the caller sees an I/O-class failure regardless of the libjpeg message code.
Definition at line 86 of file lwir_image.c.
◆ 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 ) |
Validate the frame size for its layout, then encode; see lwir_image.h.
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 | ) |
Report the bundled codec; see lwir_image.h.
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 this process published and persist the removal; see lwir_image.h.
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 the sensor view without evidence; see lwir_image.h.
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 with provenance; see lwir_image.h.
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 with provenance; see lwir_image.h.
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 the combined frame verbatim; see lwir_image.h.
Publish an exact combined frame with the same no-overwrite contract.
Definition at line 516 of file lwir_image.c.
◆ open_parent()
|
static |
Open the directory that will contain path, for fsync after linking.
- Parameters
-
path Destination path; a name without '/' resolves to ".", "/name" to "/".
- Returns
- Read-only directory descriptor (close-on-exec), or -1 with errno set; ENAMETOOLONG when the directory part exceeds PATH_MAX.
Copies the directory part with a bounded loop instead of memcpy.
Definition at line 367 of file lwir_image.c.
◆ publish()
|
static |
Durably publish a JPEG or raw companion under a new name.
- Parameters
-
path Final destination; must not exist. frame Frame to encode or copy. bytes Exact frame size (half size for image-only JPEG output). width Native width. height Native height. synthetic True for replayed/simulated frames (JPEG only). raw True writes frameverbatim instead of encoding a JPEG.evidence Optional provenance (JPEG only). render Optional display policy (JPEG only).
- Returns
- True when the file is complete, named and the directory synced. On false, errno holds the first failure (later cleanup does not overwrite it) and
pathdoes not exist: a name this call already linked is removed again.
Sequence: mkstemp "PATH.part.XXXXXX" -> write -> fflush + fsync -> link() to path -> fsync directory -> unlink temporary -> fsync directory. link() fails with EEXIST instead of replacing an existing file (unlike rename()), so publication is atomic and never overwrites. The temporary is removed on every path. Because link() refuses existing names, a name removed on rollback is always one this call created, never someone else's file.
- Note
- mkstemp creates the file owner-only (0600); the linked name keeps that mode.
Definition at line 422 of file lwir_image.c.
◆ write_provenance_markers()
|
static |
Write application provenance without taking ownership of the encoder.
- Parameters
-
encoder Started compressor; markers must precede the first scanline. width Native frame width. height Native frame height. display_width Encoded width after orientation. display_height Encoded height after orientation. synthetic True for replayed/simulated frames. evidence Optional provenance; NULL writes no APP14 or EXIF at all. render Resolved display policy (never NULL here). range Window and clipping counts from lwir_render_prepare().
- Returns
- Zero on success, otherwise the errno value the encoder owner must publish: ENOSPC when the text exceeds the fixed evidence buffer, EINVAL when the sensor-capture record cannot be encoded or serialized.
Teardown stays with the owner so marker failures retain cleanup/error ordering. Builds the APP14 text in several bounded snprintf steps; each step checks truncation so a partial key=value record is never emitted.
- Warning
- jpeg_write_marker() can still longjmp on codec failure; that unwinds straight to encode_jpeg() and bypasses this function's return value.
Definition at line 112 of file lwir_image.c.
◆ write_thermal_markers()
|
static |
Preserve exact native temperatures independently of display rendering.
- Parameters
-
encoder Started compressor; called before the first scanline. frame Combined frame; the temperature plane starts after the YUYV plane. width Native width. height Native height. synthetic Selects the LWIRSIM1 instead of the LWIRRAW1 signature.
Splits the width*height*2-byte plane into APP15 chunks of at most LWIR_THERMAL_CHUNK_CAPACITY bytes, each with the full header. Offsets are relative to the plane start and strictly sequential, which the reader enforces. Bytes are copied verbatim, so JPEG quality never touches them. Codec failures longjmp to encode_jpeg().
Definition at line 220 of file lwir_image.c.
◆ write_u32()
|
static |
Store value as four little-endian bytes.
- Parameters
-
destination At least four writable bytes. value Value to encode.
Explicit byte order keeps the APP15 header independent of host endianness.
Definition at line 74 of file lwir_image.c.
Variable Documentation
◆ encoder
| struct jpeg_compress_struct encoder |
libjpeg compressor, zeroed and recreated per photo.
Definition at line 59 of file lwir_image.c.
◆ error
| struct jpeg_error_mgr error |
Standard error manager with error_exit redirected to jpeg_failure().
Definition at line 60 of file lwir_image.c.
◆ evidence
| char evidence[8192] |
APP14 text; well below the 65533-byte APPn limit, so one marker suffices.
Definition at line 66 of file lwir_image.c.
◆ exif
| struct exif_document exif |
EXIF builder for the sensor-capture tag.
Definition at line 64 of file lwir_image.c.
◆ exif_payload
| uint8_t exif_payload[EXIF_MAX_PAYLOAD] |
Serialized EXIF APP1 payload.
Definition at line 65 of file lwir_image.c.
◆ [struct]
| struct { ... } jpeg_workspace |
Static encoder state shared by every photo.
Static storage avoids per-photo heap use and keeps worst-case memory fixed. Shared state is why the encoder is not re-entrant.
◆ marker
| uint8_t marker[LWIR_THERMAL_HEADER_BYTES+LWIR_THERMAL_CHUNK_CAPACITY] |
One APP15 chunk being assembled.
Definition at line 62 of file lwir_image.c.
◆ recovery
| jmp_buf recovery |
Target of jpeg_failure(); armed in encode_jpeg().
Definition at line 61 of file lwir_image.c.
◆ row
| uint8_t row[LWIR_MAX_WIDTH *3U] |
One interleaved YCbCr display row; the renderer is given its capacity.
Definition at line 63 of file lwir_image.c.