Crate refimage 

Crate to handle image data backed either by a contiguous slice or a vector.

The image data is stored in a row-major order and can be of different pixel types - u8, u16, and f32. The image data supports arbitrary color spaces and number of channels, but the number of channels must be consistent with the length of the backing storage. The image size is limited to 65535 x 65535 pixels. In case the image is a Bayer mosaic image, the crate supports debayering of the image data.

The crate additionally supports serialization and deserialization of the image data using the serde framework.

The crate provides a concrete type ImageRef to store image data and a type-erased version DynamicImageRef to store image data with different pixel types. Additionally, the crate provides a GenericImageRef type to store a DynamicImageRef with additional metadata, such as the image creation timestamp, and many more. The metadata keys must be 80 characters or less. Uniqueness of the keys is not enforced, but is strongly recommended; the keys are case-insensitive.

The crate, with the optional image feature, provides can convert between DynamicImageRef and DynamicImage from the image crate. With the optional fitsio feature, the crate can write a GenericImageRef, with all associated metadata, to a FITS file.

Usage

use refimage::{ImageRef, ColorSpace, DynamicImageRef, GenericImageRef, GenericImageOwned};
use refimage::chrono::DateTime;
use std::time::Duration;

let mut data = vec![1u8, 2, 3, 4, 5, 6, 0, 0]; // 3x2 grayscale image, with extra padding that will be ignored
let img = ImageRef::new(&mut data, 3, 2, ColorSpace::Gray).unwrap(); // Create ImageRef
let img = DynamicImageRef::from(img); // Convert to DynamicImageRef
let now = DateTime::from_timestamp(1_700_000_000, 0).unwrap(); // in an app: chrono::Utc::now()
let mut img = GenericImageRef::new(now, Duration::from_millis(20), img); // timestamp + exposure are mandatory
img.insert_key("CAMERANAME", "Canon EOS 5D Mark IV".to_string()).unwrap(); // Insert metadata
let serialized = bincode::serialize(&img).unwrap(); // Serialize the image
let deserialized: GenericImageOwned = bincode::deserialize(&serialized).unwrap(); // Deserialize the image

Processing pipelines

All pixel conversions — debayer, luminance, pixel-type conversion, affine pixel scaling, crop, ROI, flips, 90° rotations, aspect-preserving resize — are Ops on a declarative, reusable Pipeline. apply runs it once and returns an owned image; given a GenericImageRef it returns a GenericImageOwned with the metadata carried across unchanged. compile-ing against a concrete ImageSpec pre-allocates every buffer, yielding a Runner that processes successive frames with zero per-frame allocation (serial-tiled strategy).

FITS

GenericImageRef / GenericImageOwned can be written to the Flexible Image Transport System via the FitsWrite trait. It supports uncompressed output and the tile-compression convention with GZIP_1 and RICE_1.

Optional Features

Features are available to extend the functionalities of the core refimage data types:

• rayon: Parallelizes the luminance / demosaic / cast kernels inside the pipeline, and enables its parallel Strategy variants (enabled by default).
• grow: Lets a compiled Runner reallocate its buffers when handed a frame whose shape differs from the one it was compiled for (enabled by default).
• image: Enables TryFrom conversions between DynamicImage and DynamicImageRef, DynamicImageOwned (disabled by default).

Re-exports

pub use chrono;

Modules

pipeline

Reusable, allocation-aware processing pipelines for pixel conversion in this crate (debayer, luminance, pixel-type conversion, affine pixel scaling, crop, ROI, flips, 90° rotations, aspect-preserving resize).

Structs

AutoTile

Type-state marker: the tile shape has not been chosen yet, so both tile_rows and tile_dims are available.

FitsCompression

An opaque, resolved compression choice, built from Gzip / Rice / Hcompress (or FitsCompression::NONE) and handed to the write methods.

FitsWriter

A multi-HDU FITS file open for writing, over any Write sink (a file by default, or an in-memory buffer — handy on wasm32, which has no filesystem).

FixedTile

Type-state marker: the tile shape is fixed, so neither tile selector is in scope any more (you cannot combine tile_rows and tile_dims).

GenericImageOwned

A serializable, generic image with metadata, backed by DynamicImageOwned.

GenericImageRef

A serializable, generic image with metadata, backed by DynamicImageRef.

GenericLineItem

A metadata item.

Gzip

GZIP_1 tile compression — lossless for every pixel type.

Hcompress

HCOMPRESS_1 tile compression (H-transform + quadtree coder). Lossless at scale = 0; f32 is quantized first. Each tile must be at least 4×4; the default tiling is one whole channel plane per tile.

ImageOwned

A structure that holds image data backed by a vector.

ImageRef

A structure that holds image data backed by a slice or a vector.

ImageView

A read-only, single-type view over an image’s samples: a borrowed slice plus the shape and (optional) sub-container bit-depth tag. The immutable analogue of ImageRef.

Metadata

Image metadata: a mandatory typed core with an ordered map of extra items.

OptimumExposure

Configuration used to find the optimum exposure.

OptimumExposureBuilder

Builder for the OptimumExposure calculator.

OptimumExposureResult

Outcome of OptimumExposure::calculate / CalcOptExp::calc_opt_exp.

Quantize

Lossy quantization of f32 images, shared by Rice and Hcompress. Integer images ignore it.

Rice

RICE_1 tile compression — lossless for u8 / u16; f32 is quantized first (see quantize).

U10

A 10-bit sample stored right-aligned in a u16 (see PixelType::U10).

U12

A 12-bit sample stored right-aligned in a u16 (see PixelType::U12); see U10 for the rationale. The only difference is the saturating range, 0..=4095.

U14

A 14-bit sample stored right-aligned in a u16 (see PixelType::U14); see U10 for the rationale. The only difference is the saturating range, 0..=16383.

Enums

BayerError

Error codes for the Bayer demosaicing.

BayerPattern

Enum to describe the Bayer pattern of the image.

ColorSpace

Description of the color space of the image.

DemosaicMethod

The demosaicing algorithm to use to fill in the missing color channels.

DitherSeed

Choice of subtractive-dither seed (ZDITHER0).

DynamicImageimage

A Dynamic Image

DynamicImageOwned

Image data with a dynamic pixel type, backed by owned data.

DynamicImageRef

Image data with a dynamic pixel type, backed by a mutable slice of data.

DynamicImageView

A type-erased, read-only view over an image’s samples — the immutable analogue of DynamicImageRef, borrowed from either that or a DynamicImageOwned.

ExposureError

Errors from configuring or running the optimum-exposure calculator.

FitsCompressionKind

The algorithm behind a FitsCompression, without its settings — handy for branching on what a value selects.

FitsError

Errors produced while writing a FITS file.

GenericImage

A serializable, generic image with metadata, backed by either a GenericImageRef or a GenericImageOwned.

GenericValue

A type-erased enum to hold a metadata value.

ImageError

Errors from constructing an image or reinterpreting its backing bytes.

InteropErrorimage

Errors from converting between image::DynamicImage and this crate’s types.

MetadataError

Errors from inserting, replacing, removing, or reading metadata.

PixelType

The primitive element type of an image’s samples.

SerdeError

Errors from (de)serializing a DynamicImageOwned / DynamicImageRef to or from the crate’s internal wire format.

Constants

CAMERANAME_KEY

Key for the camera name metadata.

EXPOSURE_KEY

Name of the exposure field, reserved because Metadata stores it as a typed field rather than a map entry.

FRAMEID_KEY

Name of the frame-ID field, reserved because Metadata stores it as a typed field rather than a map entry.

PROGRAMNAME_KEY

Key for the name of the program that generated this object.

TIMESTAMP_KEY

Name of the timestamp field, reserved because Metadata stores it as a typed field rather than a map entry.

Traits

BayerShift

A trait for shifting Bayer patterns.

CalcOptExp

Trait to calculate the optimum exposure time and binning.

Deserialize

A data structure that can be deserialized from any data format supported by Serde.

Enlargeable

An Enlargable::Larger value should be enough to calculate the sum (average) of a few hundred or thousand Enlargeable values.

FitsWrite

Write an image, with its metadata, to a FITS file.

ImageProps

A trait for accessing the properties of an image.

InsertValue

Trait to insert a metadata value into a MetaCollection.

PixelData

Type-erased access to an image’s raw sample buffer.

PixelStor

The type of each channel in a pixel. For example, this can be u8, u16, f32.

Serialize

A data structure that can be serialized into any data format supported by Serde.

Functions

create_fits

Create a FITS file on disk with an empty primary HDU, ready for FitsWrite::append_fits. compress is the compression each appended image uses.

create_fits_to

Like create_fits, but writes to any Write sink instead of a path — e.g. a Vec<u8> for an in-memory multi-HDU FITS file. The empty primary HDU is written immediately.

Type Aliases

ExposureResult

Result alias for ExposureError.

FitsResult

Result alias for FitsError.

ImageResult

Result alias for ImageError.

InteropResultimage

Result alias for InteropError.

MetaCollection

A collection of metadata items, keyed by uppercase name and kept in insertion order.

MetadataResult

Result alias for MetadataError.

SerdeResult

Result alias for SerdeError.

Derive Macros

Deserialize

Serialize