Skip to content

Image.md

Latest commit

 

History

History
526 lines (438 loc) · 17.3 KB

Image.md

File metadata and controls

526 lines (438 loc) · 17.3 KB

FROG Image Library Specification

Definition of the minimal standard frog.image library for FROG
FROG - Free Open Graphical Language

Overview

This document defines the first minimal standard frog.image primitive surface and records the base image/picture/plot direction for future standardization. Its role is to provide ordinary image-data functions that can feed Picture widgets without making the Picture widget itself responsible for file reading or codec behavior.

The initial published library is intentionally small. It standardizes a portable image buffer value shape, one path-based decode primitive suitable for basic FROG programs and base IDE distributions, and three format-specific read primitives for PNG, JPEG, and BMP files. Additional base functions are listed below as candidates, not as already accepted primitives.

This is a lightweight standard library family. A base FROG distribution MAY ship an implementation for it, but programs still call it explicitly, FIR still preserves the primitive identity, and downstream lowering or packaging still decides which implementation modules and dependencies are required.

Layering Rule

A Picture widget is a display surface. It consumes image values and renders them through a realization such as the Default Picture SVG. It does not read files and it does not own image-decoding semantics.

Image file reading and decoding belongs to explicit diagram functions: 

Path control
  -> frog.image.decode_file_rgba8
  -> ImageBufferRGBA8
  -> Picture indicator

This preserves a LabVIEW-like dataflow model: the user can see the path, the decode function, the produced image value, and the Picture indicator as separate program objects.

Namespace

FROG image primitives use the frog.image.* namespace. 

frog.image.decode_file_rgba8
frog.image.read_png_file
frog.image.read_jpeg_file
frog.image.read_bmp_file

The namespace owns generic image value construction, decoding, and simple image metadata operations. Specialized computer-vision, camera, GPU, neural, inspection, calibration, or OpenCV-like functionality belongs in optional libraries, profiles, or implementation-specific packages unless explicitly standardized later.

Available Function Surface

The current published frog.image function surface is deliberately minimal:

Primitive Inputs Outputs Required baseline formats Role
frog.image.decode_file_rgba8 path image, success, error_code image/png, image/jpeg, image/bmp Decode a path-selected baseline image file into a portable frog.image.buffer_rgba8 value.
frog.image.read_png_file path image, success, error_code image/png Read a PNG file into a portable frog.image.buffer_rgba8 value.
frog.image.read_jpeg_file path image, success, error_code image/jpeg Read a JPEG file into a portable frog.image.buffer_rgba8 value.
frog.image.read_bmp_file path image, success, error_code image/bmp Read a BMP file into a portable frog.image.buffer_rgba8 value.

No other frog.image primitive is currently published by this specification. Additional image operations, encoders, camera acquisition, advanced processing, and OpenCV-like functions remain outside the current standard lightweight image-library surface unless they are explicitly standardized later.

Base Library Direction

To stay LabVIEW-like without collapsing advanced vision tooling into the base standard surface, FROG separates three related standard-library families:

Family Responsibility Status
frog.image Image buffers, basic graphics file formats, simple metadata, and pixel-buffer utilities. decode_file_rgba8, read_png_file, read_jpeg_file, and read_bmp_file are published; the remaining base functions are candidates.
frog.picture Picture construction and drawing primitives that produce a value renderable by a Picture indicator. Candidate family; no primitive is published yet.
frog.plot Simple plot-to-picture functions for waveform, XY, and multi-XY visualization. Candidate family; no primitive is published yet.

This split mirrors the practical separation between graphics format I/O, picture drawing, and plot generation. It also keeps advanced image-processing families such as thresholding, filtering, OCR, pattern matching, edge detection, camera acquisition, and OpenCV-like pipelines outside the lightweight base surface unless explicitly standardized later.

Candidate Base Functions

The following functions are base-standard candidates. They document the intended direction, but they are not considered available until promoted by a specific specification update, example, manifest contract, and implementation/conformance validation.

frog.image candidates

Candidate primitive Role Implementation note
frog.image.write_png_file(path, image) Write a frog.image.buffer_rgba8 value as PNG. Requires an image-writing provider, not only an image decoder.
frog.image.write_jpeg_file(path, image, quality) Write a frog.image.buffer_rgba8 value as JPEG. Requires an image-writing provider and an explicit quality contract.
frog.image.write_bmp_file(path, image) Write a frog.image.buffer_rgba8 value as BMP. Requires an image-writing provider.
frog.image.get_subset(image, x, y, width, height) Return a rectangular image subset. Can be implemented directly over frog.image.buffer_rgba8.
frog.image.width(image), frog.image.height(image) Return image dimensions. Simple metadata accessors over the image buffer contract.
frog.image.rgb_to_color(r, g, b), frog.image.color_to_rgb(color) Convert between RGB channels and a compact color value. The exact color scalar representation must be standardized before promotion.

frog.picture candidates

Candidate primitive Role
frog.picture.empty()Create an empty picture value.
frog.picture.draw_point(picture, x, y, color)Draw one point.
frog.picture.draw_line(picture, x1, y1, x2, y2, color, thickness)Draw one line segment.
frog.picture.draw_multiple_lines(picture, points, color, thickness)Draw a polyline or multiple connected line segments.
frog.picture.draw_rect(picture, x, y, width, height, stroke, fill, thickness)Draw a rectangle.
frog.picture.draw_round_rect(picture, x, y, width, height, radius, stroke, fill, thickness)Draw a rounded rectangle.
frog.picture.draw_oval(picture, x, y, width, height, stroke, fill, thickness)Draw an oval or ellipse.
frog.picture.draw_arc(picture, x, y, width, height, start_angle, sweep_angle, color, thickness)Draw an arc.
frog.picture.draw_text(picture, x, y, text, style)Draw text using an explicit style contract.
frog.picture.draw_pixmap(picture, x, y, image)Draw an image buffer into a picture.
frog.picture.to_image(picture)Rasterize a picture value to frog.image.buffer_rgba8.

The exact picture value representation, clipping behavior, anti-aliasing rules, text-font contract, flattened pixmap representation, and coordinate origin are intentionally left for a later frog.picture specification pass.

frog.plot candidates

Candidate primitive Role
frog.plot.waveform(data, options)Render waveform data to a picture value.
frog.plot.xy(x_values, y_values, options)Render one XY plot to a picture value.
frog.plot.multi_xy(series, options)Render multiple XY series to a picture value.
frog.plot.legend(series, options)Render a plot legend component or picture value.

Plot functions are rendering helpers, not advanced signal-processing or chart history widgets. They may produce a picture value that a Picture indicator can display, or they may later be paired with dedicated plot/graph widget realizations.

Image Buffer Type

The initial portable output type is frog.image.buffer_rgba8. Conceptually it is a row-major RGBA image buffer: 

{
  "kind": "image_buffer",
  "pixel_format": "rgba8",
  "width": u32,
  "height": u32,
  "stride_bytes": u32,
  "pixels": array<u8>,
  "color_space": "srgb",
  "origin": "top_left"
}

Rules:

  • pixels stores rows from top to bottom.
  • Each pixel has four bytes in red, green, blue, alpha order.
  • stride_bytes MUST be at least width * 4.
  • For a tightly packed buffer, stride_bytes = width * 4.
  • An empty fallback buffer uses width = 0, height = 0, stride_bytes = 0, and an empty pixels array.

Primitive: frog.image.decode_file_rgba8

Decodes an image file identified by a path into a portable RGBA8 image buffer.

  • input port: path
  • output ports: image, success, error_code

Types:

  • path: path or string according to the active source/profile posture
  • image: frog.image.buffer_rgba8
  • success: bool
  • error_code: string

The first standardized format set is:

  • image/png
  • image/jpeg
  • image/bmp

Implementations MAY support additional formats, but a program that requires additional formats should declare that requirement explicitly through the appropriate profile, dependency, or package metadata.

Failure Behavior

If decoding fails, the primitive MUST return:

  • success = false,
  • an empty frog.image.buffer_rgba8,
  • a stable error_code.

Initial error codes:

  • ok
  • invalid_path
  • not_found
  • unsupported_format
  • decode_failed

Primitive: frog.image.read_png_file

Reads a PNG file identified by a path into a portable RGBA8 image buffer. The result shape, failure behavior, and error codes are the same as frog.image.decode_file_rgba8. If the selected path is not a PNG file, the primitive returns unsupported_format.

  • input port: path
  • output ports: image, success, error_code
  • required format: image/png

Primitive: frog.image.read_jpeg_file

Reads a JPEG file identified by a path into a portable RGBA8 image buffer. The result shape, failure behavior, and error codes are the same as frog.image.decode_file_rgba8. If the selected path is not a JPEG file, the primitive returns unsupported_format.

  • input port: path
  • output ports: image, success, error_code
  • required format: image/jpeg

Primitive: frog.image.read_bmp_file

Reads a BMP file identified by a path into a portable RGBA8 image buffer. The result shape, failure behavior, and error codes are the same as frog.image.decode_file_rgba8. If the selected path is not a BMP file, the primitive returns unsupported_format.

  • input port: path
  • output ports: image, success, error_code
  • required format: image/bmp

Implementation Dependency Posture

The public FROG specification defines the frog.image primitive contract. It does not require a specific codec implementation.

A base IDE or runtime distribution MAY implement frog.image.decode_file_rgba8 and the format-specific read primitives with a small dependency such as stb_image, and MAY later replace or complement that implementation with codec-specific libraries such as PNG or JPEG libraries. Such choices are implementation details as long as the public FROG contract remains satisfied.

This separation keeps the dependency replaceable: 

FROG program contract: frog.image.decode_file_rgba8 / read_png_file / read_jpeg_file / read_bmp_file
Implementation choice: stb_image, libpng/libspng, libjpeg-turbo, or another codec stack

The implementation dependency belongs to the selected runtime, launcher, IDE distribution, or compiled deployment closure. It does not change the FROG primitive contract and it does not make image decoding a hidden responsibility of the Picture widget.

Standard Provider and Deployment Closure

An implementation MAY realize the published frog.image read primitives through a shared library, static library, compiled object, built-in provider, generated backend artifact, or another equivalent provider mechanism.

The public requirement is that the provider satisfies the called frog.image primitive contract and that the dependency remains declared in the relevant FIR, lowering, manifest, package, profile, or deployment closure. The public FROG specification does not require one mandatory runtime loading mechanism.

This keeps deployment modular. A program that does not use frog.image does not need an image provider. A compiled launcher or self-contained executable that does use a published frog.image read primitive may carry only the image provider needed by that program, together with the program's other selected dependencies and assets.

Implementations MAY keep their provider source code, optimization strategy, packaging layout, and runtime-loader architecture private, provided the public primitive contract and declared dependency boundary remain intact.

Out of Scope for the Initial Image Library

  • any candidate function listed above until it is explicitly promoted,
  • camera acquisition,
  • GPU image surfaces,
  • OpenCV-style image processing,
  • region-of-interest algorithms,
  • color-management profiles beyond the initial srgb contract,
  • streaming or tiled image decode.

Those capabilities may be standardized later or supplied by external FROG libraries and native dependency packages.

End of FROG Image Library Specification