Expand description
Deterministic previews of OpenReadout datasets, drawn with the figure engine
(openreadout-figure) and encoded as PNG, JPEG or SVG.
- Images: one plane, a channel composite (additive, channel colours from the normalized
model) or a maximum-intensity projection over z or t, read from the pyramid level nearest the
requested size when the reader exposes levels, then resampled to the requested size (area
average; a small image is enlarged by repeating its pixels) and mapped to 8 bits
with a contrast rule (
auto,min-max,percentile:LO,HI,raw). By default the picture is framed by coordinate rulers in full-resolution pixels (and a scale bar when the pixel size is known), andImagePreviewreports how PNG pixels map back to source pixels, so a viewer can read coordinates off the image and ask for aregionof it. - Traces: one sweep, one panel per channel (min/max envelope per pixel column, so spikes
survive any downsampling), with ticked axes in the trace’s units (time, NMR chemical shift,
wavenumber, …). Spectra and chromatograms get their largest peaks labelled; current-clamp
sweeps can get their action potentials marked (
Marks). qPCR curves are overlaid. - Spectra: one mass spectrum, as sticks (centroided) or a profile line, the largest peaks labelled with their m/z.
- Plates: a heat map of a multi-well plate table (columns named like wells
A1…P24, orwell/row+columncolumns); a kinetic read becomes a grid of small growth curves in plate positions, coloured by the plate layout’s groups. - Events: flow cytometry events as a density plot of two parameters (or a histogram of one).
Callers can draw their own Annotations on any preview (points, boxes, outlines, arrows,
text, lines and bands), in full-resolution pixels on images and in axis units on plots;
PreviewOutput::annotations says where each one landed.
Every step uses fixed-order arithmetic and no threads, so the same request produces the same bytes on every run.
§Example
Previewing a file is render (read and draw) followed by finish (encode):
use openreadout_core::{Dataset, Result};
use openreadout_preview::{Encoding, PreviewRequest, finish, render};
fn png_preview(dataset: &mut dyn Dataset) -> Result<Vec<u8>> {
let info = dataset.info()?;
let mut request = PreviewRequest::default(); // image 0, channel 0, middle Z, 1024 px
request.max_size = 512;
let rendered = render(dataset, &info, &request)?;
let (output, png) = finish(&rendered, Encoding::Png, 90)?;
println!("{} x {} px, xxh3 {}", output.width, output.height, output.xxh3);
Ok(png)
}The drawing and encoding layers work without a file:
use openreadout_preview::{Encoding, Raster, encode};
let mut raster = Raster::new(4, 2, [0, 0, 0]);
raster.set(0, 0, [255, 255, 255]);
let png = encode(&raster, Encoding::Png, 90)?;
assert_eq!(&png[1..4], b"PNG");Modules§
- color
- Colours: channel colours from the normalized model, the documented default palette, a wavelength-to-colour mapping, and the sequential colour map used by plate heat maps.
- electrochem
- Voltammetry previews: current against potential, the way a voltammogram is read, instead of
each channel against time. Each cycle (the reader’s
cyclechannel, or each sweep when a file stores cycles as sweeps) is one loop, from faint (first) to ink (last).
Structs§
- Annotation
- One annotation, in the coordinates the picture shows: full-resolution pixels on images (as on the rulers), axis units on plots (as on the tick labels), and on plate curve grids the time and value axes every card shares.
- Chromatogram
Preview - Details of a chromatogram preview of a mass-spectrometry run (its first look).
- Data
Mark - A mark drawn from the data: a labelled peak or a detected action potential.
- Drawn
Annotation - An annotation as drawn: the request, plus where it landed in PNG pixels.
- Events
Preview - Details of an event (flow cytometry) preview.
- Figure
- A figure: a canvas size, a background and the items drawn on it, in order.
- Image
Preview - Details of an image preview.
- Plate
Grid - The values of a plate table, one per well, as the heat map shows them.
- Plate
Group - One layout group of a plate preview (a SoftMax Pro group, a sample name, …).
- Plate
Preview - Details of a plate preview.
- Plot
Panel - One plot panel inside the picture, for mapping PNG pixels to data values and back: the
value at the panel’s left edge is
x[0], at its right edgex[1], at its bottomy[0]and at its topy[1], along the scale named inx_scale/y_scale. - Preview
Channel - One channel of an image preview.
- Preview
Options - Preview options by name. Every field is optional;
PreviewOptions::requestfills in the defaults. The MCP toolopenreadout_previewtakes these fields as its arguments, so their documentation is also what an agent reads. - Preview
Output - Output of
preview: what was rendered, and where it went. - Preview
Request - What to render.
Defaultpreviews image 0 (middle z, t 0, channel 0) at 1024 px. - PxRect
- A rectangle in PNG pixels (fractional).
- Raster
- An 8-bit RGB image, row-major, no padding.
- Rendered
- A rendered preview before encoding.
- Scale
Bar - The scale bar drawn under an image preview.
- Source
Point - A point in full-resolution (level 0) source pixel coordinates.
- Spectrum
Preview - Details of a mass-spectrum preview.
- Trace
Preview - Details of a trace preview.
- Trace
Preview Channel - One channel of a trace preview.
- XAxis
- The horizontal axis of a trace or spectrum preview.
Enums§
- Annotation
Type - What an annotation draws.
- Axes
- What frames an image preview.
- Axis
- Axis of a projection (maximum or sum).
- Contrast
- How sample values map to display brightness.
- Encoding
- Output encoding.
- Lut
- Colour lookup for a single channel.
- Marks
- Marks drawn from the data itself.
- View
- Which plane of a volume an image preview shows.
Constants§
- DEFAULT_
JPEG_ QUALITY - Default JPEG quality.
- DEFAULT_
PREVIEW_ SIZE - Default
max_size. - DEFAULT_
THUMBNAIL_ READ_ BYTES - Default budget of decoded pixel bytes a
thumbnailmay read (32 MiB). - DEFAULT_
THUMBNAIL_ SIZE - Default longest side of a
thumbnail. - LOG_
PERCENTILES - Percentiles of
logcontrast without numbers: the median (the background) and the 99.9th. - MAX_
ANNOTATIONS - Most annotations one picture takes.
- MAX_
CAPTION_ CHARS - Longest caption, in characters.
- MAX_
CHANNELS - Most trace channels one picture draws.
- MAX_
PREVIEW_ SIZE - Largest
max_sizeaccepted (pixels on the longer side). - MAX_
TITLE_ CHARS - Longest title, in characters.
- MIN_
TRACE_ SAMPLES_ OVER_ SPECTRUM - A file with both traces and spectra previews its first trace by default only when some trace has at least this many samples (a chromatogram of a real run); otherwise spectrum 0.
- WINDOW_
PRESETS - Named CT display windows:
(name, center, width)in Hounsfield units.
Functions§
- default_
output - Default output path:
<input stem>.preview.<png|jpg|svg>next to the input. - encode
- Encode a raster as PNG (8-bit greyscale when every pixel is grey, else RGB) or JPEG. SVG
needs the figure: use
finish. - encode_
figure - Encode a figure at its own size: PNG, JPEG or SVG.
- finish
- Encode a rendered preview and fill in the size, encoding and hash.
- finish_
within - Encode within a byte budget (for inline MCP image content): the requested encoding first,
then JPEG at quality 85, then halving the image until it fits.
encodingin the output says when the image became a JPEG. Halving adds one note, worded for the person looking at the picture. - plate_
grid - The per-well values of table
table(default 0);columnpicks the value column of a long table. Errors when the table has no well layout. - render
- Render a preview (no encoding yet).
- series_
index_ of - The theme series colour (index into
Theme::series) that shows a base or a dye the way analysis software does, in the figure engine’s palette: A green, C blue, G ink, T red; FAM blue, VIC/HEX/JOE green, NED/TAMRA ochre (yellow on screen), PET/ROX red, LIZ brown (orange on screen).Nonefor other names. The preview, the plot and the viewer colour these series by this index. - split_
select - Split combined selections:
["c=0,1,z=2"]→["c=0,1", "z=2"](a comma followed byaxis=starts a new selection). Plain repeatablec=0arguments pass through. - thumbnail
- A small look at a file’s first image for a summary (“auto-screenshot”): channel 0 (or a
composite of 2–4 channels), middle z, t 0, from the smallest pyramid level that still covers
max_size, with rulers. Fails (unsupported) instead of decoding more thanmax_read_bytesof pixels, and on any read error: the caller skips the thumbnail and points torenderwith a region or level. - write_
verified - Write
bytestooutputthrough a temporary file that is read back and compared before it is renamed into place. Refuses to replace an existing file unlessoverwrite, and refuses to write over the input however its path is spelled. Returnstrue(verified).