use crate::error::{Result, Tm25Error};
pub const MAGIC: [u8; 4] = *b"TM25";
pub const VERSION_2013: i32 = 2013;
pub const HEADER_BLOCK_SIZE: usize = 256;
pub const FLAGS_OFFSET: usize = 256;
pub const TEXT_OFFSET: usize = 288;
pub const TEXT_FIELD_CHARS: usize = 1000;
pub const TEXT_FIELDS: usize = 9;
pub const FIXED_HEADER_SIZE: usize = TEXT_OFFSET + TEXT_FIELDS * TEXT_FIELD_CHARS * 4; pub const DATE_TIME_LEN: usize = 28;
pub const COLUMN_NAME_BYTES: usize = 512;
pub const COLUMN_NAME_CHARS: usize = COLUMN_NAME_BYTES / 4;
pub const BLOCK_ALIGN: usize = 32;
pub(crate) fn spectral_padding(bytes: usize) -> usize {
(BLOCK_ALIGN - bytes % BLOCK_ALIGN) % BLOCK_ALIGN
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SpectralId {
None,
SingleWavelength,
PerRayWavelength,
SharedTable,
PerRayTableIndex,
Unknown(i32),
}
impl SpectralId {
pub fn from_i32(v: i32) -> Self {
match v {
0 => SpectralId::None,
1 => SpectralId::SingleWavelength,
2 => SpectralId::PerRayWavelength,
3 => SpectralId::SharedTable,
4 => SpectralId::PerRayTableIndex,
other => SpectralId::Unknown(other),
}
}
pub fn to_i32(self) -> i32 {
match self {
SpectralId::None => 0,
SpectralId::SingleWavelength => 1,
SpectralId::PerRayWavelength => 2,
SpectralId::SharedTable => 3,
SpectralId::PerRayTableIndex => 4,
SpectralId::Unknown(v) => v,
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub struct KnownDataFlags {
pub position: bool,
pub direction: bool,
pub radiant_flux: bool,
pub wavelength: bool,
pub luminous_flux: bool,
pub stokes: bool,
pub tristimulus: bool,
pub spectrum_index: bool,
}
impl KnownDataFlags {
pub fn radiometric() -> Self {
Self {
position: true,
direction: true,
radiant_flux: true,
..Default::default()
}
}
pub fn photometric() -> Self {
Self {
position: true,
direction: true,
luminous_flux: true,
..Default::default()
}
}
fn from_words(w: &[i32; 8]) -> Self {
Self {
position: w[0] != 0,
direction: w[1] != 0,
radiant_flux: w[2] != 0,
wavelength: w[3] != 0,
luminous_flux: w[4] != 0,
stokes: w[5] != 0,
tristimulus: w[6] != 0,
spectrum_index: w[7] != 0,
}
}
pub(crate) fn to_words(self) -> [i32; 8] {
[
self.position as i32,
self.direction as i32,
self.radiant_flux as i32,
self.wavelength as i32,
self.luminous_flux as i32,
self.stokes as i32,
self.tristimulus as i32,
self.spectrum_index as i32,
]
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FluxKind {
Radiometric,
Photometric,
Both,
}
#[derive(Clone, Debug, PartialEq, Eq, Default)]
pub struct TextFields {
pub raw: [String; TEXT_FIELDS],
}
impl TextFields {
pub fn name(&self) -> &str {
&self.raw[0]
}
pub fn manufacturer(&self) -> &str {
&self.raw[1]
}
pub fn model_creator(&self) -> &str {
&self.raw[2]
}
pub fn rayfile_creator(&self) -> &str {
&self.raw[3]
}
pub fn equipment(&self) -> &str {
&self.raw[4]
}
pub fn camera(&self) -> &str {
&self.raw[5]
}
pub fn operating_condition(&self) -> &str {
&self.raw[6]
}
pub fn additional_info(&self) -> &str {
&self.raw[7]
}
pub fn data_reference(&self) -> &str {
&self.raw[8]
}
}
#[derive(Clone, Debug, PartialEq, Default)]
pub struct SpectralTable {
pub wavelengths_nm: Vec<f32>,
pub values: Vec<f32>,
}
impl SpectralTable {
pub fn len(&self) -> usize {
self.wavelengths_nm.len()
}
pub fn is_empty(&self) -> bool {
self.wavelengths_nm.is_empty()
}
pub fn peak(&self) -> Option<(f32, f32)> {
self.wavelengths_nm
.iter()
.zip(&self.values)
.map(|(&w, &v)| (w, v))
.fold(None, |best, cur| match best {
Some((_, bv)) if bv >= cur.1 => best,
_ => Some(cur),
})
}
pub fn centroid_nm(&self) -> Option<f32> {
let sum: f32 = self.values.iter().sum();
if sum <= 0.0 {
return None;
}
let m: f32 = self
.wavelengths_nm
.iter()
.zip(&self.values)
.map(|(w, v)| w * v)
.sum();
Some(m / sum)
}
pub fn is_ultraviolet(&self) -> bool {
let total: f32 = self.values.iter().sum();
if total <= 0.0 {
return false;
}
let uv: f32 = self
.wavelengths_nm
.iter()
.zip(&self.values)
.filter(|(w, _)| **w < 400.0)
.map(|(_, v)| v)
.sum();
uv / total > 0.9
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Column {
X,
Y,
Z,
Kx,
Ky,
Kz,
RadiantFlux,
Wavelength,
LuminousFlux,
S1,
S2,
S3,
PolX,
PolY,
PolZ,
TriX,
TriZ,
SpectrumIndex,
Additional(usize),
}
pub fn columns_from_flags(flags: &KnownDataFlags, n_additional: usize) -> Vec<Column> {
let mut c = vec![
Column::X,
Column::Y,
Column::Z,
Column::Kx,
Column::Ky,
Column::Kz,
];
if flags.radiant_flux {
c.push(Column::RadiantFlux);
}
if flags.wavelength {
c.push(Column::Wavelength);
}
if flags.luminous_flux {
c.push(Column::LuminousFlux);
}
if flags.stokes {
c.extend([
Column::S1,
Column::S2,
Column::S3,
Column::PolX,
Column::PolY,
Column::PolZ,
]);
}
if flags.tristimulus {
c.extend([Column::TriX, Column::TriZ]);
}
if flags.spectrum_index {
c.push(Column::SpectrumIndex);
}
for i in 0..n_additional {
c.push(Column::Additional(i));
}
c
}
#[derive(Clone, Copy, Debug)]
pub struct ParseOptions {
pub strict_flags: bool,
pub total_size: Option<u64>,
}
impl Default for ParseOptions {
fn default() -> Self {
Self {
strict_flags: true,
total_size: None,
}
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct Header {
pub version: i32,
pub creation_method: i32,
pub luminous_flux_lm: f32,
pub radiant_flux_w: f32,
pub n_rays: u64,
pub date_time: String,
pub start_position: i32,
pub spectral_id: SpectralId,
pub single_wavelength_nm: Option<f32>,
pub min_wavelength_nm: Option<f32>,
pub max_wavelength_nm: Option<f32>,
pub n_additional_items: usize,
pub additional_text_size: i32,
pub flags: KnownDataFlags,
pub text: TextFields,
pub spectra: Vec<SpectralTable>,
pub column_names: Vec<String>,
pub additional_text: String,
pub(crate) raw_flux_bits: Option<(u32, u32)>,
pub nan_pattern: u32,
pub columns: Vec<Column>,
pub ray_start: usize,
}
impl Header {
pub fn record_size(&self) -> usize {
self.columns.len() * 4
}
pub fn ray_block_size(&self) -> u64 {
self.n_rays * self.record_size() as u64
}
pub fn flux_kind(&self) -> FluxKind {
match (self.flags.radiant_flux, self.flags.luminous_flux) {
(true, true) => FluxKind::Both,
(false, true) => FluxKind::Photometric,
_ => FluxKind::Radiometric,
}
}
pub fn total_flux(&self, kind: FluxKind) -> f32 {
match kind {
FluxKind::Radiometric | FluxKind::Both => self.radiant_flux_w,
FluxKind::Photometric => self.luminous_flux_lm,
}
}
pub fn column_index(&self, col: Column) -> Option<usize> {
self.columns.iter().position(|c| *c == col)
}
pub fn shared_spectrum(&self) -> Option<&SpectralTable> {
match self.spectral_id {
SpectralId::SharedTable => self.spectra.first(),
_ => None,
}
}
pub fn new(flags: KnownDataFlags) -> Self {
Self {
version: VERSION_2013,
creation_method: 0,
luminous_flux_lm: 0.0,
radiant_flux_w: 0.0,
n_rays: 0,
date_time: String::new(),
start_position: 0,
spectral_id: SpectralId::None,
single_wavelength_nm: None,
min_wavelength_nm: None,
max_wavelength_nm: None,
n_additional_items: 0,
additional_text_size: 0,
flags,
text: TextFields::default(),
spectra: Vec::new(),
column_names: Vec::new(),
additional_text: String::new(),
raw_flux_bits: None,
nan_pattern: f32::NAN.to_bits(),
columns: columns_from_flags(&flags, 0),
ray_start: 0,
}
}
pub fn parse(bytes: &[u8], opts: &ParseOptions) -> Result<Header> {
let mut r = Cursor::new(bytes);
let magic = r.bytes4()?;
if magic != MAGIC {
return Err(Tm25Error::BadMagic(magic));
}
let version = r.i32()?;
if version != VERSION_2013 {
return Err(Tm25Error::UnsupportedVersion(version));
}
let creation_method = r.i32()?;
let raw_luminous = r.f32()?;
let raw_radiant = r.f32()?;
let raw_flux_bits = Some((raw_luminous.to_bits(), raw_radiant.to_bits()));
let luminous_flux_lm = zero_if_unknown(raw_luminous);
let radiant_flux_w = zero_if_unknown(raw_radiant);
let n_rays = r.u64()?;
let date_raw = r.take(DATE_TIME_LEN)?;
let date_time = date_raw
.iter()
.take_while(|b| **b != 0)
.map(|b| *b as char)
.collect::<String>()
.trim()
.to_string();
let start_position = r.i32()?;
let spectral_id = SpectralId::from_i32(r.i32()?);
let raw_single = r.f32()?;
let raw_min = r.f32()?;
let raw_max = r.f32()?;
let nan_pattern = [raw_single, raw_min, raw_max]
.iter()
.find(|v| is_unknown(**v))
.map(|v| v.to_bits())
.unwrap_or_else(|| f32::NAN.to_bits());
let single_wavelength_nm = opt_f32(raw_single);
let min_wavelength_nm = opt_f32(raw_min);
let max_wavelength_nm = opt_f32(raw_max);
let n_spectra = r.i32()?;
let n_additional_items = r.i32()?;
let additional_text_size = r.i32()?;
if n_spectra < 0 || n_additional_items < 0 || additional_text_size < 0 {
return Err(Tm25Error::InvalidHeader(format!(
"negative counts: spectra {n_spectra}, additional items {n_additional_items}, text {additional_text_size}"
)));
}
if n_spectra > 10_000 || n_additional_items > 1_000 || additional_text_size > 10_000_000 {
return Err(Tm25Error::InvalidHeader(format!(
"implausible counts: spectra {n_spectra}, additional items {n_additional_items}, text {additional_text_size}"
)));
}
r.seek(FLAGS_OFFSET)?;
let mut words = [0i32; 8];
for w in words.iter_mut() {
*w = r.i32()?;
}
let flags = KnownDataFlags::from_words(&words);
r.seek(TEXT_OFFSET)?;
let mut text = TextFields::default();
for (i, slot) in text.raw.iter_mut().enumerate() {
*slot = r.utf32_fixed(TEXT_FIELD_CHARS, TEXT_FIELD_NAMES[i])?;
}
r.seek(FIXED_HEADER_SIZE)?;
let mut spectra = Vec::with_capacity(n_spectra as usize);
for _ in 0..n_spectra {
let n = r.i32()?;
if !(0..=1_000_000).contains(&n) {
return Err(Tm25Error::InvalidHeader(format!(
"implausible spectral table size {n}"
)));
}
let mut t = SpectralTable {
wavelengths_nm: Vec::with_capacity(n as usize),
values: Vec::with_capacity(n as usize),
};
for _ in 0..n {
t.wavelengths_nm.push(r.f32()?);
t.values.push(r.f32()?);
}
spectra.push(t);
}
let spectral_bytes = r.pos - FIXED_HEADER_SIZE;
r.take(spectral_padding(spectral_bytes))?;
let mut column_names = Vec::with_capacity(n_additional_items as usize);
for _ in 0..n_additional_items {
column_names.push(r.utf32_fixed(COLUMN_NAME_CHARS, "column name")?);
}
if additional_text_size % 4 != 0 {
return Err(Tm25Error::InvalidHeader(format!(
"additional text size {additional_text_size} is not a multiple of 4"
)));
}
let additional_text =
r.utf32_exact(additional_text_size as usize / 4, "additional text")?;
let ray_start = r.pos;
let columns = columns_from_flags(&flags, n_additional_items as usize);
let header = Header {
version,
creation_method,
luminous_flux_lm,
radiant_flux_w,
n_rays,
date_time,
start_position,
spectral_id,
single_wavelength_nm,
min_wavelength_nm,
max_wavelength_nm,
n_additional_items: n_additional_items as usize,
additional_text_size,
flags,
text,
spectra,
column_names,
additional_text,
raw_flux_bits,
nan_pattern,
columns,
ray_start,
};
if opts.strict_flags {
header.validate()?;
}
Ok(header)
}
pub fn validate(&self) -> Result<()> {
let f = &self.flags;
let bad = |msg: &str| Err(Tm25Error::InvalidHeader(msg.to_string()));
if !f.position || !f.direction {
return bad("position and direction flags must be set");
}
if !f.radiant_flux && !f.luminous_flux {
return bad("both radiant and luminous flux flags are missing");
}
match self.spectral_id {
SpectralId::PerRayWavelength => {
if !f.wavelength {
return bad("spectral id 2 (per-ray wavelength) requires the wavelength flag");
}
if !f.radiant_flux {
return bad("spectral id 2 requires the radiant flux flag");
}
}
SpectralId::SharedTable => {
if self.spectra.is_empty() {
return bad("spectral id 3 (shared table) but no spectral table");
}
}
SpectralId::PerRayTableIndex => {
if !f.spectrum_index {
return bad("spectral id 4 requires the spectrum index flag");
}
if !f.radiant_flux {
return bad("spectral id 4 requires the radiant flux flag");
}
if self.spectra.is_empty() {
return bad("spectral id 4 but no spectral tables");
}
}
_ => {}
}
if f.spectrum_index && self.spectral_id != SpectralId::PerRayTableIndex {
return bad("spectrum index flag requires spectral id 4");
}
if f.stokes && !f.radiant_flux {
return bad("Stokes flag requires the radiant flux flag");
}
if f.tristimulus && (!f.luminous_flux || self.spectral_id != SpectralId::None) {
return bad("tristimulus flag requires the luminous flux flag and spectral id 0");
}
for (i, t) in self.spectra.iter().enumerate() {
if t.wavelengths_nm.iter().any(|w| w.is_nan() || *w <= 0.0) {
return Err(Tm25Error::InvalidHeader(format!(
"spectral table {i} has a non-positive wavelength"
)));
}
if t.values.iter().any(|v| v.is_nan() || *v < 0.0) {
return Err(Tm25Error::InvalidHeader(format!(
"spectral table {i} has a negative or NaN value"
)));
}
}
Ok(())
}
}
pub(crate) const TEXT_FIELD_NAMES: [&str; TEXT_FIELDS] = [
"name",
"manufacturer",
"model creator",
"ray file creator",
"equipment",
"camera",
"operating condition",
"additional info",
"data reference",
];
fn is_unknown(v: f32) -> bool {
const BYTE_SWAPPED_SENTINEL: u32 = 0x0100_807F;
v.is_nan() || v.to_bits() == BYTE_SWAPPED_SENTINEL
}
fn zero_if_unknown(v: f32) -> f32 {
if is_unknown(v) {
0.0
} else {
v
}
}
fn opt_f32(v: f32) -> Option<f32> {
if is_unknown(v) {
None
} else {
Some(v)
}
}
pub(crate) struct Cursor<'a> {
bytes: &'a [u8],
pub(crate) pos: usize,
}
impl<'a> Cursor<'a> {
pub(crate) fn new(bytes: &'a [u8]) -> Self {
Self { bytes, pos: 0 }
}
fn need(&self, n: usize) -> Result<()> {
let needed = self.pos.saturating_add(n);
if needed > self.bytes.len() {
Err(Tm25Error::Truncated {
needed,
have: self.bytes.len(),
})
} else {
Ok(())
}
}
fn take(&mut self, n: usize) -> Result<&'a [u8]> {
self.need(n)?;
let s = &self.bytes[self.pos..self.pos + n];
self.pos += n;
Ok(s)
}
fn seek(&mut self, pos: usize) -> Result<()> {
if pos > self.bytes.len() {
return Err(Tm25Error::Truncated {
needed: pos,
have: self.bytes.len(),
});
}
self.pos = pos;
Ok(())
}
fn bytes4(&mut self) -> Result<[u8; 4]> {
let s = self.take(4)?;
Ok([s[0], s[1], s[2], s[3]])
}
fn i32(&mut self) -> Result<i32> {
Ok(i32::from_le_bytes(self.bytes4()?))
}
fn u32(&mut self) -> Result<u32> {
Ok(u32::from_le_bytes(self.bytes4()?))
}
fn f32(&mut self) -> Result<f32> {
Ok(f32::from_le_bytes(self.bytes4()?))
}
fn u64(&mut self) -> Result<u64> {
let s = self.take(8)?;
let mut b = [0u8; 8];
b.copy_from_slice(s);
Ok(u64::from_le_bytes(b))
}
fn utf32_fixed(&mut self, chars: usize, field: &'static str) -> Result<String> {
let start = self.pos;
self.need(chars * 4)?;
let mut out = String::new();
for i in 0..chars {
let cp = self.u32()?;
if cp == 0 {
break;
}
match char::from_u32(cp) {
Some(c) => out.push(c),
None => {
return Err(Tm25Error::InvalidText {
field,
code_point: cp,
});
}
}
let _ = i;
}
self.pos = start + chars * 4;
Ok(out)
}
fn utf32_exact(&mut self, chars: usize, field: &'static str) -> Result<String> {
self.need(chars.saturating_mul(4))?;
let mut out = String::with_capacity(chars);
for _ in 0..chars {
let cp = self.u32()?;
if cp == 0 {
continue;
}
match char::from_u32(cp) {
Some(c) => out.push(c),
None => {
return Err(Tm25Error::InvalidText {
field,
code_point: cp,
})
}
}
}
Ok(out)
}
}