#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![allow(clippy::many_single_char_names)]
pub mod canvas;
pub mod color;
mod image;
pub mod jpeg;
mod overlay;
mod plate;
mod rulers;
mod spectrum;
mod trace;
use std::path::{Path, PathBuf};
use std::str::FromStr;
use openreadout_core::model::FileInfo;
use openreadout_core::reader::Dataset;
use openreadout_core::{Error, Result};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
pub use canvas::Canvas;
pub use plate::{PlateGrid, plate_grid};
pub const MAX_PREVIEW_SIZE: u32 = 8192;
pub const DEFAULT_PREVIEW_SIZE: u32 = 1024;
pub const DEFAULT_JPEG_QUALITY: u8 = 90;
pub const DEFAULT_THUMBNAIL_SIZE: u32 = 384;
pub const DEFAULT_THUMBNAIL_READ_BYTES: u64 = 32 << 20;
pub const MIN_TRACE_SAMPLES_OVER_SPECTRUM: u64 = 100;
#[derive(Debug, Clone, Copy, PartialEq, Default)]
#[non_exhaustive]
pub enum Contrast {
#[default]
Auto,
MinMax,
Percentile(f64, f64),
Raw,
}
impl FromStr for Contrast {
type Err = Error;
fn from_str(s: &str) -> Result<Self> {
let s = s.trim().to_ascii_lowercase();
match s.as_str() {
"auto" => Ok(Contrast::Auto),
"min-max" | "minmax" => Ok(Contrast::MinMax),
"raw" => Ok(Contrast::Raw),
_ => {
let bad = || {
Error::Usage(format!(
"bad contrast '{s}': use auto, min-max, raw or percentile:LO,HI (e.g. percentile:1,99)"
))
};
let spec = s.strip_prefix("percentile:").ok_or_else(bad)?;
let (a, b) = spec.split_once(',').ok_or_else(bad)?;
let (a, b): (f64, f64) = (
a.trim().parse().map_err(|_| bad())?,
b.trim().parse().map_err(|_| bad())?,
);
if !(0.0..=100.0).contains(&a) || !(0.0..=100.0).contains(&b) || a >= b {
return Err(bad());
}
Ok(Contrast::Percentile(a, b))
}
}
}
}
impl std::fmt::Display for Contrast {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Contrast::Auto => f.write_str("auto"),
Contrast::MinMax => f.write_str("min-max"),
Contrast::Percentile(a, b) => write!(f, "percentile:{a},{b}"),
Contrast::Raw => f.write_str("raw"),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "kebab-case")]
#[non_exhaustive]
pub enum Lut {
#[serde(alias = "grey")]
Gray,
#[serde(alias = "channel-colour", alias = "color")]
ChannelColor,
}
impl FromStr for Lut {
type Err = Error;
fn from_str(s: &str) -> Result<Self> {
match s.trim().to_ascii_lowercase().as_str() {
"gray" | "grey" => Ok(Lut::Gray),
"channel-color" | "channel-colour" | "color" => Ok(Lut::ChannelColor),
other => Err(Error::Usage(format!(
"bad lut '{other}': use gray or channel-color"
))),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum Axis {
Z,
T,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum Axes {
#[default]
Rulers,
Grid,
None,
}
impl Axes {
pub fn apply(self, req: &mut PreviewRequest) {
req.axes = self != Axes::None;
req.grid = self == Axes::Grid;
}
}
impl FromStr for Axes {
type Err = Error;
fn from_str(s: &str) -> Result<Self> {
match s.trim().to_ascii_lowercase().as_str() {
"rulers" => Ok(Axes::Rulers),
"grid" => Ok(Axes::Grid),
"none" => Ok(Axes::None),
other => Err(Error::Usage(format!(
"bad axes '{other}': use rulers, grid or none"
))),
}
}
}
impl FromStr for Axis {
type Err = Error;
fn from_str(s: &str) -> Result<Self> {
match s.trim().to_ascii_lowercase().as_str() {
"z" => Ok(Axis::Z),
"t" => Ok(Axis::T),
other => Err(Error::Usage(format!(
"bad projection axis '{other}': use z or t"
))),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum Encoding {
#[default]
Png,
#[serde(alias = "jpg")]
Jpeg,
}
impl Encoding {
pub fn as_str(self) -> &'static str {
match self {
Encoding::Png => "png",
Encoding::Jpeg => "jpeg",
}
}
pub fn mime(self) -> &'static str {
match self {
Encoding::Png => "image/png",
Encoding::Jpeg => "image/jpeg",
}
}
pub fn extension(self) -> &'static str {
match self {
Encoding::Png => "png",
Encoding::Jpeg => "jpg",
}
}
pub fn from_path(p: &Path) -> Self {
match p
.extension()
.and_then(|e| e.to_str())
.map(str::to_ascii_lowercase)
.as_deref()
{
Some("jpg" | "jpeg") => Encoding::Jpeg,
_ => Encoding::Png,
}
}
}
impl FromStr for Encoding {
type Err = Error;
fn from_str(s: &str) -> Result<Self> {
match s.trim().to_ascii_lowercase().as_str() {
"png" => Ok(Encoding::Png),
"jpeg" | "jpg" => Ok(Encoding::Jpeg),
other => Err(Error::Usage(format!(
"bad preview format '{other}': use png or jpeg"
))),
}
}
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct PreviewRequest {
pub image: Option<u32>,
pub select: Vec<String>,
pub mip: Option<Axis>,
pub composite: bool,
pub level: Option<u32>,
pub region: Option<openreadout_core::Region>,
pub max_size: u32,
pub contrast: Contrast,
pub lut: Option<Lut>,
pub trace: Option<u32>,
pub sweep: Option<u32>,
pub channels: Vec<u32>,
pub run: Option<u32>,
pub spectrum: Option<u64>,
pub scan: Option<u64>,
pub centroid: bool,
pub table: Option<u32>,
pub column: Option<String>,
pub axes: bool,
pub grid: bool,
pub max_read_bytes: Option<u64>,
}
impl Default for PreviewRequest {
fn default() -> Self {
PreviewRequest {
image: None,
select: Vec::new(),
mip: None,
composite: false,
level: None,
region: None,
max_size: DEFAULT_PREVIEW_SIZE,
contrast: Contrast::Auto,
lut: None,
trace: None,
sweep: None,
channels: Vec::new(),
run: None,
spectrum: None,
scan: None,
centroid: false,
table: None,
column: None,
axes: true,
grid: false,
max_read_bytes: None,
}
}
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct PreviewChannel {
pub index: u32,
#[serde(skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
pub color: String,
pub color_source: String,
pub display_min: f64,
pub display_max: f64,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct SourcePoint {
pub x: f64,
pub y: f64,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ScaleBar {
pub length: f64,
pub unit: String,
pub length_um: f64,
pub pixels: u32,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct ImagePreview {
pub image: u32,
pub level: u32,
pub source_width: u32,
pub source_height: u32,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub region: Option<openreadout_core::Region>,
pub downsample: u32,
pub c: Vec<u32>,
pub z: Vec<u32>,
pub t: Vec<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub projection: Option<String>,
pub composite: bool,
pub rgb: bool,
pub contrast: String,
pub lut: String,
pub channels: Vec<PreviewChannel>,
#[serde(default)]
pub axes: bool,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub grid: bool,
#[serde(default)]
pub plot_area: openreadout_core::Region,
#[serde(default)]
pub source_origin: SourcePoint,
#[serde(default)]
pub source_per_pixel: f64,
#[serde(default)]
pub source_per_pixel_y: f64,
#[serde(default)]
pub full_res_region: openreadout_core::Region,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub scale_bar: Option<ScaleBar>,
}
impl ImagePreview {
fn halve(&mut self) {
let (plot, origin, per) = rulers::halve(
self.plot_area,
self.source_origin,
(self.source_per_pixel, self.source_per_pixel_y),
);
self.plot_area = plot;
self.source_origin = origin;
(self.source_per_pixel, self.source_per_pixel_y) = per;
if let Some(b) = &mut self.scale_bar {
b.pixels = b.pixels.div_ceil(2);
}
}
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct TracePreviewChannel {
pub index: u32,
pub name: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub unit: Option<String>,
pub color: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub min: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub max: Option<f64>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct XAxis {
pub quantity: String,
pub unit: String,
pub first: f64,
pub last: f64,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct TracePreview {
pub trace: u32,
pub sweep: u32,
pub sample_rate_hz: f64,
pub sweep_sample_count: u64,
pub sample_count: u64,
pub truncated: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub x_axis: Option<XAxis>,
pub channels: Vec<TracePreviewChannel>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct SpectrumPreview {
pub run: u32,
pub index: u64,
pub scan_number: u64,
pub ms_level: u32,
pub rt_s: Option<f64>,
pub style: String,
pub point_count: u64,
pub x_axis: XAxis,
#[serde(skip_serializing_if = "Option::is_none")]
pub max_intensity: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub precursor_mz: Option<f64>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct PlatePreview {
pub table: u32,
pub layout: String,
pub rows: u32,
pub columns: u32,
pub wells: u32,
pub value: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub min: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub max: Option<f64>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct PreviewOutput {
pub path: String,
pub format: String,
pub kind: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub output: Option<String>,
pub encoding: String,
pub width: u32,
pub height: u32,
pub bytes: u64,
pub xxh3: String,
pub verified: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub image: Option<ImagePreview>,
#[serde(skip_serializing_if = "Option::is_none")]
pub trace: Option<TracePreview>,
#[serde(skip_serializing_if = "Option::is_none")]
pub spectrum: Option<SpectrumPreview>,
#[serde(skip_serializing_if = "Option::is_none")]
pub plate: Option<PlatePreview>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub notes: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub hint: Option<String>,
}
impl PreviewOutput {
fn halved(&mut self) {
if let Some(im) = &mut self.image {
im.halve();
}
}
}
#[derive(Debug, Clone)]
pub struct Rendered {
pub canvas: Canvas,
pub output: PreviewOutput,
}
pub fn split_select(args: &[String]) -> Vec<String> {
let mut out: Vec<String> = Vec::new();
for a in args {
let mut cur = String::new();
for part in a.split(',') {
if part.contains('=') && !cur.is_empty() {
out.push(std::mem::take(&mut cur));
}
if !cur.is_empty() {
cur.push(',');
}
cur.push_str(part.trim());
}
if !cur.is_empty() {
out.push(cur);
}
}
out
}
fn kind(info: &FileInfo, req: &PreviewRequest) -> Result<&'static str> {
if req.table.is_some() || req.column.is_some() {
return Ok("plate");
}
if req.trace.is_some() || req.sweep.is_some() || !req.channels.is_empty() {
return Ok("trace");
}
if req.run.is_some() || req.spectrum.is_some() || req.scan.is_some() || req.centroid {
return Ok("spectrum");
}
let short_traces = info
.traces
.iter()
.all(|t| t.sample_count < MIN_TRACE_SAMPLES_OVER_SPECTRUM);
if !info.images.is_empty() {
Ok("image")
} else if !info.traces.is_empty() && (!short_traces || info.spectra.is_empty()) {
Ok("trace")
} else if !info.spectra.is_empty() {
Ok("spectrum")
} else if !info.tables.is_empty() {
Ok("plate")
} else {
Err(Error::unsupported(
"preview",
format!("preview of a {} file", info.format.name),
"This file holds no images, traces, spectra or tables to draw; see `openreadout info`.",
))
}
}
pub fn render(ds: &mut dyn Dataset, info: &FileInfo, req: &PreviewRequest) -> Result<Rendered> {
if req.max_size < 16 || req.max_size > MAX_PREVIEW_SIZE {
return Err(Error::Usage(format!(
"max size {} out of range (16..={MAX_PREVIEW_SIZE})",
req.max_size
)));
}
let k = kind(info, req)?;
let mut out = PreviewOutput {
path: info.path.clone(),
format: info.format.id.clone(),
kind: k.into(),
..PreviewOutput::default()
};
let canvas = match k {
"image" => image::render(ds, info, req, &mut out)?,
"trace" => trace::render(ds, info, req, &mut out)?,
"spectrum" => spectrum::render(ds, info, req, &mut out)?,
_ => plate::render(ds, info, req, &mut out)?,
};
let mut canvas = canvas;
while canvas.width.max(canvas.height) > req.max_size {
canvas = canvas.half();
out.halved();
out.notes.push(format!(
"layout larger than max size {}; halved to {}x{}",
req.max_size, canvas.width, canvas.height
));
}
Ok(Rendered {
canvas,
output: out,
})
}
pub fn encode(c: &Canvas, encoding: Encoding, jpeg_quality: u8) -> Result<Vec<u8>> {
match encoding {
Encoding::Jpeg => {
if c.width > 65_535 || c.height > 65_535 {
return Err(Error::Usage("JPEG previews are limited to 65535 px".into()));
}
Ok(jpeg::encode(c, jpeg_quality))
}
Encoding::Png => {
let mut buf = Vec::new();
let gray = c.is_gray();
{
let mut e = png::Encoder::new(&mut buf, c.width, c.height);
e.set_color(if gray {
png::ColorType::Grayscale
} else {
png::ColorType::Rgb
});
e.set_depth(png::BitDepth::Eight);
e.set_compression(png::Compression::Balanced);
let mut w = e
.write_header()
.map_err(|e| Error::Other(format!("PNG encoding failed: {e}")))?;
let data: Vec<u8> = if gray {
c.rgb.as_chunks::<3>().0.iter().map(|p| p[0]).collect()
} else {
c.rgb.clone()
};
w.write_image_data(&data)
.map_err(|e| Error::Other(format!("PNG encoding failed: {e}")))?;
w.finish()
.map_err(|e| Error::Other(format!("PNG encoding failed: {e}")))?;
}
Ok(buf)
}
}
}
fn xxh3_hex(b: &[u8]) -> String {
format!("{:032x}", xxhash_rust::xxh3::xxh3_128(b))
}
pub fn finish(
r: &Rendered,
encoding: Encoding,
jpeg_quality: u8,
) -> Result<(PreviewOutput, Vec<u8>)> {
let bytes = encode(&r.canvas, encoding, jpeg_quality)?;
let mut out = r.output.clone();
out.encoding = encoding.as_str().into();
out.width = r.canvas.width;
out.height = r.canvas.height;
out.bytes = bytes.len() as u64;
out.xxh3 = xxh3_hex(&bytes);
Ok((out, bytes))
}
pub fn finish_within(
r: &Rendered,
encoding: Encoding,
jpeg_quality: u8,
max_bytes: usize,
) -> Result<(PreviewOutput, Vec<u8>)> {
let (mut out, mut bytes) = finish(r, encoding, jpeg_quality)?;
if bytes.len() <= max_bytes {
return Ok((out, bytes));
}
let mut cur = r.clone();
let mut enc = encoding;
if enc == Encoding::Png {
enc = Encoding::Jpeg;
(out, bytes) = finish(&cur, enc, 85)?;
}
let mut halved = false;
while bytes.len() > max_bytes && cur.canvas.width.max(cur.canvas.height) > 32 {
cur.canvas = cur.canvas.half();
cur.output.halved();
(out, bytes) = finish(&cur, enc, 85)?;
halved = true;
}
if halved {
out.notes.push(format!(
"shown at reduced resolution ({}x{} px); preview a region for full detail",
cur.canvas.width, cur.canvas.height
));
}
Ok((out, bytes))
}
pub fn thumbnail(
ds: &mut dyn Dataset,
info: &FileInfo,
max_size: u32,
max_read_bytes: u64,
) -> Result<Rendered> {
let im = info.images.first().ok_or_else(|| {
Error::unsupported(
"preview",
"thumbnail of a file without images",
"Use `preview` for traces, spectra and plates.",
)
})?;
let mut req = PreviewRequest {
image: Some(im.index),
max_size,
max_read_bytes: Some(max_read_bytes),
composite: im.samples_per_pixel != 3 && (2..=4).contains(&im.size_c),
..PreviewRequest::default()
};
match render(ds, info, &req) {
Err(Error::Unsupported { .. }) if req.composite => {
req.composite = false;
render(ds, info, &req)
}
other => other,
}
}
pub fn default_output(input: &Path, encoding: Encoding) -> PathBuf {
let stem = input
.file_stem()
.map_or_else(|| "preview".into(), |s| s.to_string_lossy().to_string());
input.with_file_name(format!("{stem}.preview.{}", encoding.extension()))
}
pub fn write_verified(input: &Path, output: &Path, bytes: &[u8], overwrite: bool) -> Result<bool> {
if output == input
|| (output.exists()
&& std::fs::canonicalize(output).ok() == std::fs::canonicalize(input).ok())
{
return Err(Error::Usage(
"output path must differ from the input; raw files are never modified".into(),
));
}
if output.exists() && !overwrite {
return Err(Error::Usage(format!(
"{} exists; pass --overwrite to replace it",
output.display()
)));
}
let tmp = output.with_file_name(format!(
".{}.partial-{}",
output
.file_name()
.map_or_else(|| "preview".into(), |s| s.to_string_lossy().to_string()),
std::process::id()
));
std::fs::write(&tmp, bytes).map_err(|e| Error::io(&tmp, e))?;
let same = std::fs::read(&tmp).is_ok_and(|b| b == bytes);
if !same {
let _ = std::fs::remove_file(&tmp);
return Err(Error::Other(
"read-back verification failed; preview discarded".into(),
));
}
std::fs::rename(&tmp, output).map_err(|e| {
let _ = std::fs::remove_file(&tmp);
Error::io(output, e)
})?;
Ok(true)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_options() {
assert_eq!("auto".parse::<Contrast>().unwrap(), Contrast::Auto);
assert_eq!(
"percentile:1,99".parse::<Contrast>().unwrap(),
Contrast::Percentile(1.0, 99.0)
);
assert!("percentile:99,1".parse::<Contrast>().is_err());
assert!("bright".parse::<Contrast>().is_err());
assert_eq!("channel-color".parse::<Lut>().unwrap(), Lut::ChannelColor);
assert_eq!("Z".parse::<Axis>().unwrap(), Axis::Z);
assert_eq!(Encoding::from_path(Path::new("a.JPG")), Encoding::Jpeg);
assert_eq!(Encoding::from_path(Path::new("a")), Encoding::Png);
}
#[test]
fn splits_combined_selection() {
assert_eq!(
split_select(&["c=0,1,z=2".into(), "t=3".into()]),
vec!["c=0,1", "z=2", "t=3"]
);
assert_eq!(split_select(&["z=1-3".into()]), vec!["z=1-3"]);
}
}