Skip to main content

Crate openreadout_preview

Crate openreadout_preview 

Source
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), and ImagePreview reports how PNG pixels map back to source pixels, so a viewer can read coordinates off the image and ask for a region of 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, or well / row + column columns); 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 cycle channel, 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.
ChromatogramPreview
Details of a chromatogram preview of a mass-spectrometry run (its first look).
DataMark
A mark drawn from the data: a labelled peak or a detected action potential.
DrawnAnnotation
An annotation as drawn: the request, plus where it landed in PNG pixels.
EventsPreview
Details of an event (flow cytometry) preview.
Figure
A figure: a canvas size, a background and the items drawn on it, in order.
ImagePreview
Details of an image preview.
PlateGrid
The values of a plate table, one per well, as the heat map shows them.
PlateGroup
One layout group of a plate preview (a SoftMax Pro group, a sample name, …).
PlatePreview
Details of a plate preview.
PlotPanel
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 edge x[1], at its bottom y[0] and at its top y[1], along the scale named in x_scale / y_scale.
PreviewChannel
One channel of an image preview.
PreviewOptions
Preview options by name. Every field is optional; PreviewOptions::request fills in the defaults. The MCP tool openreadout_preview takes these fields as its arguments, so their documentation is also what an agent reads.
PreviewOutput
Output of preview: what was rendered, and where it went.
PreviewRequest
What to render. Default previews 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.
ScaleBar
The scale bar drawn under an image preview.
SourcePoint
A point in full-resolution (level 0) source pixel coordinates.
SpectrumPreview
Details of a mass-spectrum preview.
TracePreview
Details of a trace preview.
TracePreviewChannel
One channel of a trace preview.
XAxis
The horizontal axis of a trace or spectrum preview.

Enums§

AnnotationType
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 thumbnail may read (32 MiB).
DEFAULT_THUMBNAIL_SIZE
Default longest side of a thumbnail.
LOG_PERCENTILES
Percentiles of log contrast 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_size accepted (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. encoding in 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); column picks 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). None for 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 by axis= starts a new selection). Plain repeatable c=0 arguments 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 than max_read_bytes of pixels, and on any read error: the caller skips the thumbnail and points to render with a region or level.
write_verified
Write bytes to output through a temporary file that is read back and compared before it is renamed into place. Refuses to replace an existing file unless overwrite, and refuses to write over the input however its path is spelled. Returns true (verified).