craft-image-codecs: Sun Raster image reader and writer

Adds Format::SunRaster: 1-, 8- (gray or colour-mapped), 24- and 32-bit
files, uncompressed or byte-encoded (RLE) on read, uncompressed on write.

Closes #1560
This commit is contained in:
el-j committed 2026-11-15 11:49:53 +01:00
1 parent 7581345a22
commit 5628ad359d
6 files changed
+267 -2

No files matched your search

+1
View File
@@ -56,6 +56,7 @@ craft-image-codecs = { git = "https://github.com/storytold/craft-libs", rev = "<
| Cineon | yes | yes | U16 (10-bit code values read and written exactly through U16) | Gray, RGB | no | no | no | no | no | no | no | built in |
| DICOM | yes | **no** | U8, U16 | Gray, RGB | no | no | no | no | no | no | n/a | built in |
| Amiga IFF (ILBM/PBM) | yes | yes (24-bit ILBM) | U8 | RGB, RGBA | yes (1-bit mask plane on write) | no | no | no | no | no | no | built in |
| Sun Raster (`.ras`) | yes (incl. RLE and colour maps) | yes (uncompressed) | U8 | Gray, Gray+A, RGB, RGBA | yes | no | no | no | no | no | no | built in |
| AVIF | **no** | only with feature `avif` | U8 | RGB, RGBA | yes | no | no | no | no | no | yes | `image` + `ravif` |
| HEIF/HEIC | with feature `heif` | **no** | U8, U16 (10/12-bit decodes to U16) | RGB, RGBA | yes (auxiliary alpha) | yes (`colr` prof) | yes | yes | no | no | n/a | `heic-rs` |
+1
View File
@@ -17,6 +17,7 @@ pub(crate) mod jxl;
pub(crate) mod pcx;
pub(crate) mod png;
pub(crate) mod pnm;
pub(crate) mod sunraster;
pub(crate) mod tga;
pub(crate) mod tiff;
pub(crate) mod tiff_exif;
+237
View File
@@ -0,0 +1,237 @@
//! Sun Raster files (`.ras`, `.sun`): 1-bit, 8-bit (gray or colour-mapped), 24-bit RGB and 32-bit
//! RGBA, uncompressed or byte-encoded (RLE) on read; uncompressed on write.
//!
//! Follows the published rasterfile format: a 32-byte big-endian header, an optional colour map,
//! then rows padded to an even number of bytes. In the "standard" type (1) 24- and 32-bit pixels
//! are stored blue-first; in the "RGB" type (3) red-first. Other types (TIFF, IFF, experimental)
//! are reported as unsupported.
use crate::error::CodecError;
use crate::fidelity::Plan;
use crate::format::Format;
use crate::image::{ChannelLayout, Image, SampleType};
use crate::options::Limits;
const F: Format = Format::SunRaster;
const HEADER: usize = 32;
const MAGIC: u32 = 0x59a6_6a95;
fn bad(reason: impl std::fmt::Display) -> CodecError {
CodecError::malformed(F, reason)
}
fn be32(b: &[u8], i: usize) -> u32 {
u32::from_be_bytes([b[i], b[i + 1], b[i + 2], b[i + 3]])
}
/// Whether `b` starts with a Sun rasterfile header.
pub(crate) fn looks_like_sunraster(b: &[u8]) -> bool {
b.len() >= HEADER && be32(b, 0) == MAGIC && matches!(be32(b, 12), 1 | 8 | 24 | 32)
}
/// Expand byte-encoded data (`0x80` escapes a run) until `want` bytes are produced.
fn unrle(src: &[u8], want: usize) -> Result<Vec<u8>, CodecError> {
let mut out = Vec::new();
out.try_reserve_exact(want).map_err(|_| bad("pixel buffer is too large"))?;
let mut i = 0;
while out.len() < want {
let b = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?;
i += 1;
if b != 0x80 {
out.push(b);
continue;
}
let n = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?;
i += 1;
if n == 0 {
out.push(0x80);
continue;
}
let v = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?;
i += 1;
let count = usize::from(n) + 1;
if count > want - out.len() {
return Err(bad("RLE run passes the end of the image"));
}
out.resize(out.len() + count, v);
}
Ok(out)
}
pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if !looks_like_sunraster(b) {
return Err(bad("invalid Sun raster header"));
}
let (w, h, depth, kind, map_type, map_len) = (be32(b, 4), be32(b, 8), be32(b, 12) as usize, be32(b, 20), be32(b, 24), be32(b, 28) as usize);
if !matches!(kind, 0..=3) {
return Err(CodecError::unsupported(F, format!("Sun raster type {kind} is not supported")));
}
if map_type > 2 {
return Err(CodecError::unsupported(F, format!("Sun raster map type {map_type} is not supported")));
}
let layout = match depth {
1 | 8 if map_type != 1 => ChannelLayout::Gray,
1 | 8 | 24 => ChannelLayout::Rgb,
_ => ChannelLayout::Rgba,
};
limits.check(w, h, layout, SampleType::U8)?;
let (wu, hu) = (w as usize, h as usize);
let stride = wu.checked_mul(depth).and_then(|n| n.checked_add(15)).ok_or_else(|| bad("image size overflow"))? / 16 * 2;
let want = stride.checked_mul(hu).ok_or_else(|| bad("image size overflow"))?;
let data_at = HEADER.checked_add(map_len).ok_or_else(|| bad("colour map size overflow"))?;
let map = b.get(HEADER..data_at).ok_or_else(|| bad("truncated colour map"))?;
let rest = &b[data_at..];
let raw;
let rows: &[u8] = if kind == 2 {
raw = unrle(rest, want)?;
&raw
} else {
rest.get(..want).ok_or_else(|| bad("the file is too short for the declared image"))?
};
let channels = layout.channels();
let mut out = Vec::new();
out.try_reserve_exact(wu * hu * channels).map_err(|_| bad("pixel buffer is too large"))?;
let entries = map_len / 3;
for y in 0..hu {
let row = &rows[y * stride..(y + 1) * stride];
for x in 0..wu {
match depth {
1 => {
// A set bit is black.
let bit = (row[x / 8] >> (7 - x % 8)) & 1;
out.push(if bit == 1 { 0 } else { 255 });
}
8 if map_type == 1 => {
let i = usize::from(row[x]);
if i >= entries {
return Err(bad("pixel index is outside the colour map"));
}
out.extend_from_slice(&[map[i], map[entries + i], map[2 * entries + i]]);
}
8 => out.push(row[x]),
24 => {
let p = &row[3 * x..3 * x + 3];
out.extend_from_slice(&if kind == 3 { [p[0], p[1], p[2]] } else { [p[2], p[1], p[0]] });
}
_ => {
let p = &row[4 * x..4 * x + 4];
out.extend_from_slice(&if kind == 3 { [p[1], p[2], p[3], p[0]] } else { [p[3], p[2], p[1], p[0]] });
}
}
}
}
Image::from_u8(w, h, layout, out)
}
/// Writes an uncompressed rasterfile: 8-bit gray, 24-bit RGB or 32-bit RGBA, in the RGB-ordered type.
pub(crate) fn encode(src: &Image, plan: Plan) -> Result<Vec<u8>, CodecError> {
let enc = |msg: String| CodecError::encode(F, msg);
let img = src.converted(plan.layout, plan.sample);
if img.sample_type() != SampleType::U8 {
return Err(enc(format!("Sun raster stores 8 bits per channel, not {:?}", img.sample_type())));
}
let depth: usize = match img.layout() {
ChannelLayout::Gray => 8,
ChannelLayout::Rgb => 24,
ChannelLayout::Rgba => 32,
l => return Err(enc(format!("no Sun raster layout for {l:?}"))),
};
let (w, h) = img.dimensions();
let (wu, hu) = (w as usize, h as usize);
let bytes = depth / 8;
let stride = (wu * bytes).next_multiple_of(2);
let len = stride.checked_mul(hu).and_then(|n| u32::try_from(n).ok()).ok_or_else(|| enc("image too large".into()))?;
let data = img.data();
if data.len() != wu * hu * bytes {
return Err(enc("the image has the wrong number of samples".into()));
}
let mut out = Vec::with_capacity(HEADER + len as usize);
for v in [MAGIC, w, h, depth as u32, len, 3, 0, 0] {
out.extend_from_slice(&v.to_be_bytes());
}
for y in 0..hu {
let row = &data[y * wu * bytes..(y + 1) * wu * bytes];
if depth == 32 {
// Stored alpha first.
for p in row.as_chunks::<4>().0 {
out.extend_from_slice(&[p[3], p[0], p[1], p[2]]);
}
} else {
out.extend_from_slice(row);
}
out.resize(HEADER + (y + 1) * stride, 0);
}
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
fn pattern(w: u32, h: u32, layout: ChannelLayout) -> Image {
let n = w as usize * h as usize * layout.channels();
Image::from_u8(w, h, layout, (0..n).map(|i| ((i * 13 + i / 3) % 253) as u8).collect()).unwrap()
}
#[test]
fn round_trips_gray_rgb_and_rgba_with_odd_widths() {
for layout in [ChannelLayout::Gray, ChannelLayout::Rgb, ChannelLayout::Rgba] {
let img = pattern(13, 7, layout);
let bytes = encode(&img, Plan { layout, sample: SampleType::U8 }).unwrap();
assert!(looks_like_sunraster(&bytes));
let back = decode(&bytes, &Limits::default()).unwrap();
assert_eq!((back.layout(), back.data()), (layout, img.data()));
}
}
fn file(depth: u32, kind: u32, map: &[u8], map_type: u32, w: u32, h: u32, data: &[u8]) -> Vec<u8> {
let mut f = Vec::new();
for v in [MAGIC, w, h, depth, data.len() as u32, kind, map_type, map.len() as u32] {
f.extend_from_slice(&v.to_be_bytes());
}
f.extend_from_slice(map);
f.extend_from_slice(data);
f
}
#[test]
fn standard_type_is_blue_first_and_rle_expands() {
let f = file(24, 1, &[], 0, 1, 1, &[1, 2, 3, 0]);
assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[3, 2, 1]);
// 0x80 0x00 is a literal 0x80; 0x80 n v is n + 1 copies of v. The 2x2 image has stride 2.
let f = file(8, 2, &[], 0, 2, 2, &[0x80, 0x00, 0x80, 0x00, 0x80, 0x01, 7]);
assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[0x80, 0x80, 7, 7]);
// A run that passes the end of the image is an error.
assert!(decode(&file(8, 2, &[], 0, 2, 2, &[0x80, 0x09, 7]), &Limits::default()).is_err());
}
#[test]
fn colour_mapped_and_one_bit_files() {
// Two entries: red plane, green plane, blue plane.
let map = [10, 20, 30, 40, 50, 60];
let f = file(8, 1, &map, 1, 2, 1, &[0, 1]);
let img = decode(&f, &Limits::default()).unwrap();
assert_eq!((img.layout(), img.data()), (ChannelLayout::Rgb, &[10, 30, 50, 20, 40, 60][..]));
let f = file(8, 1, &map, 1, 1, 1, &[5, 0]);
assert!(decode(&f, &Limits::default()).is_err());
let f = file(1, 1, &[], 0, 3, 1, &[0b1010_0000, 0]);
assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[0, 255, 0]);
}
#[test]
fn hostile_input_is_an_error_not_a_panic() {
let img = pattern(9, 5, ChannelLayout::Rgb);
let good = encode(&img, Plan { layout: ChannelLayout::Rgb, sample: SampleType::U8 }).unwrap();
for len in 0..good.len() {
let _ = decode(&good[..len], &Limits::default());
}
let mut huge = good.clone();
huge[4..8].copy_from_slice(&u32::MAX.to_be_bytes());
huge[8..12].copy_from_slice(&u32::MAX.to_be_bytes());
assert!(decode(&huge, &Limits::default()).is_err());
let mut bad_map = good;
bad_map[28..32].copy_from_slice(&u32::MAX.to_be_bytes());
assert!(decode(&bad_map, &Limits::default()).is_err());
assert!(matches!(decode(&file(24, 4, &[], 0, 1, 1, &[0; 4]), &Limits::default()), Err(CodecError::Unsupported { .. })));
}
}
+11 -1
View File
@@ -44,6 +44,8 @@ pub enum Format {
Iff,
/// JPEG 2000 (JP2 container or raw J2K codestream): read-only; see [`ASYMMETRIC_EXCEPTIONS`].
Jp2,
/// Sun Raster (`.ras`): 1-, 8-, 24- and 32-bit, uncompressed or RLE.
SunRaster,
}
/// What a format can hold **and** what this crate reads/writes for it.
@@ -113,7 +115,7 @@ const TIFF_LAYOUTS: &[ChannelLayout] = &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::
impl Format {
/// Every format known to the crate (enabled or not).
pub const ALL: [Format; 24] = [
pub const ALL: [Format; 25] = [
Format::Png,
Format::Jpeg,
Format::Jp2,
@@ -138,6 +140,7 @@ impl Format {
Format::Cineon,
Format::Dicom,
Format::Iff,
Format::SunRaster,
];
pub fn caps(self) -> FormatCaps {
@@ -176,6 +179,7 @@ impl Format {
Format::Dicom => "DICOM",
Format::Iff => "Amiga IFF",
Format::Jp2 => "JPEG 2000",
Format::SunRaster => "Sun Raster",
}
}
@@ -207,6 +211,7 @@ impl Format {
Format::Dicom => &["dcm", "dicom", "dc3"],
Format::Iff => &["iff", "lbm", "ilbm"],
Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"],
Format::SunRaster => &["ras", "sun"],
}
}
@@ -236,6 +241,7 @@ impl Format {
Format::Dicom => "application/dicom",
Format::Iff => "image/x-iff",
Format::Jp2 => "image/jp2",
Format::SunRaster => "image/x-sun-raster",
}
}
@@ -310,6 +316,7 @@ pub fn caps(format: Format) -> FormatCaps {
Format::Cineon => FormatCaps { depths: &[S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Dicom => FormatCaps { read: true, write: false, depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Iff => FormatCaps { depths: &[S::U8], layouts: &[L::Rgb, L::Rgba], alpha: true, ..base },
Format::SunRaster => FormatCaps { layouts: &[L::Gray, L::Rgb, L::Rgba], alpha: true, ..base },
Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base },
}
}
@@ -388,6 +395,9 @@ pub fn detect(bytes: &[u8]) -> Option<Format> {
if b.starts_with(b"/* XPM */") || b.starts_with(b"! XPM2\n") || b.starts_with(b"! XPM2\r\n") {
return Some(Format::Xpm);
}
if crate::codecs::sunraster::looks_like_sunraster(b) {
return Some(Format::SunRaster);
}
if crate::codecs::pcx::looks_like_pcx(b) {
return Some(Format::Pcx);
}
+3 -1
View File
@@ -62,7 +62,7 @@ pub use crate::resolution::{exif_resolution, export_exif, export_xmp, photoshop_
pub use crate::source_settings::{WebpEncoding, jpeg_quality, webp_encoding};
pub use half::f16;
use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, tiff, via_image, webp, xpm};
use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, sunraster, tiff, via_image, webp, xpm};
/// Detect the format and decode with default [`Limits`].
pub fn decode(bytes: &[u8]) -> Result<Image, CodecError> {
@@ -101,6 +101,7 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res
Format::Cineon => dpx::decode_cineon(bytes, l),
Format::Dicom => dicom::decode(bytes, l),
Format::Iff => iff::decode(bytes, l),
Format::SunRaster => sunraster::decode(bytes, l),
Format::OpenExr => exr::decode(bytes, l),
Format::Heif => heif::decode(bytes, l, opts.keep_orientation),
Format::Jp2 => jp2::decode(bytes, l),
@@ -457,6 +458,7 @@ pub fn encode(image: &Image, format: Format, opts: &EncodeOptions) -> Result<Vec
Format::Cineon => dpx::encode_cineon(image, plan),
Format::Dicom => Err(CodecError::unsupported(format, "DICOM is import-only; save as TIFF or PNG instead")),
Format::Iff => iff::encode(image, plan),
Format::SunRaster => sunraster::encode(image, plan),
Format::OpenExr => exr::encode(image, plan, opts),
Format::Heif => Err(CodecError::unsupported(format, "encoding is not available in this build")),
Format::Jp2 => Err(CodecError::unsupported(format, "JPEG 2000 is import-only; save as PNG or TIFF instead")),
@@ -62,6 +62,7 @@ fn default_build_formats_all_symmetric() {
Format::Dpx,
Format::Cineon,
Format::Iff,
Format::SunRaster,
];
for f in expected {
assert!(caps(f).read && caps(f).write, "{f:?}");
@@ -218,6 +219,19 @@ fn detect_magic_iff() {
assert_eq!(detect(b"FORM\0\0\0\x14AIFF"), None);
assert!(decode_as(Format::Iff, b"FORM\0\0\0\x14ILBM").is_err());
}
#[test]
fn detect_magic_sun_raster() {
use craft_image_codecs::{ChannelLayout, EncodeOptions, Image, encode};
let img = Image::from_u8(5, 3, ChannelLayout::Rgb, (0..45).collect()).unwrap();
let bytes = encode(&img, Format::SunRaster, &EncodeOptions::default()).unwrap();
assert_eq!(detect(&bytes), Some(Format::SunRaster));
assert_eq!(from_extension("scan.RAS"), Some(Format::SunRaster));
assert_eq!(decode(&bytes).unwrap().data(), img.data());
assert!(!ASYMMETRIC_EXCEPTIONS.iter().any(|(f, _)| *f == Format::SunRaster));
assert_eq!(detect(&[0x59, 0xa6, 0x6a, 0x95]), None);
assert!(decode_as(Format::SunRaster, &[0x59, 0xa6, 0x6a, 0x95]).is_err());
}
#[test]
fn detect_magic_avif() {
assert_eq!(detect(b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf"), Some(Format::Avif));