Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! The file as stored: header, color mode data, image resources, layer
//! records with their channel data, document-level tagged blocks, and the
//! merged image, each kept as its bytes so that an unedited file writes
//! back byte for byte.
//!
//! [`read`] splits a `.psd` or `.psb` file into a [`PsdFile`]; [`write()`]
//! joins one back. Neither interprets pixels or tagged blocks: the
//! [`crate::channels`] codecs decode channel data, and the [`crate::codec`]
//! modules decode blocks. High-bit documents keep their layers in a
//! document-level `Lr16` or `Lr32` block; [`LayerSection::info`] holds them
//! wherever they are stored ([`LayerSection::info_key`]).
//!
//! Padding is kept only where a file departs from what Photoshop writes,
//! so a changed or new part gets Photoshop's layout: tagged blocks padded
//! to four bytes (counted in the length inside layer records, not at the
//! document level), names padded to four, the layer info padded to four.
//! Damaged files never panic: what cannot be split becomes a
//! [`PsdError::Corrupt`] error or, past the essentials, bytes kept as they
//! are ([`LayerRecord::extra_tail`], [`LayerSection::tail`]).
mod read;
mod write;
use crate::error::{PsdError, Result};
use crate::raster::IRect;
/// The file header.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Header {
/// 1 for `.psd`, 2 for `.psb` (large document format).
pub version: u16,
/// Channels of the merged image, alpha channels included.
pub channels: u16,
/// Canvas height in pixels.
pub height: u32,
/// Canvas width in pixels.
pub width: u32,
/// Bits per channel: 1, 8, 16, or 32.
pub depth: u16,
/// Color mode code ([`crate::model::ColorMode::code`]).
pub mode: u16,
}
impl Header {
/// Whether the file is a large document (`.psb`), which widens some
/// lengths to 64 bits.
pub fn is_psb(&self) -> bool {
self.version == 2
}
}
/// An image resource block.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Resource {
/// `8BIM` (or another signature some writers use).
pub signature: [u8; 4],
/// Resource id (1005 resolution, 1032 guides, 1036 thumbnail, …).
pub id: u16,
/// The resource's Pascal name, without its length byte.
pub name: Vec<u8>,
/// The resource's data, without padding.
pub data: Vec<u8>,
}
impl Resource {
/// An `8BIM` resource with no name.
pub fn new(id: u16, data: Vec<u8>) -> Resource {
Resource {
signature: *b"8BIM",
id,
name: Vec::new(),
data,
}
}
}
/// How channel data is compressed.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Compression {
/// Uncompressed.
Raw,
/// PackBits run-length encoding, rows counted up front.
#[default]
Rle,
/// Deflate.
Zip,
/// Deflate over differences between neighboring samples.
ZipPrediction,
}
impl Compression {
/// The code files store.
pub fn code(self) -> u16 {
match self {
Compression::Raw => 0,
Compression::Rle => 1,
Compression::Zip => 2,
Compression::ZipPrediction => 3,
}
}
/// The compression a code names.
pub fn from_code(code: u16) -> Option<Compression> {
Some(match code {
0 => Compression::Raw,
1 => Compression::Rle,
2 => Compression::Zip,
3 => Compression::ZipPrediction,
_ => return None,
})
}
}
/// One channel of a layer's image data, as stored.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Channel {
/// 0, 1, 2… color channels; -1 transparency; -2 the layer mask; -3 the
/// real user mask (when a layer has both a pixel and a vector mask).
pub id: i16,
/// How `bytes` is compressed.
pub compression: Compression,
/// The compressed samples (after the two-byte compression code).
pub bytes: Vec<u8>,
}
/// Optional parameters a layer mask may carry.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct MaskParams {
/// User mask density, `0..=255`.
pub user_density: Option<u8>,
/// User mask feather, in pixels.
pub user_feather: Option<f64>,
/// Vector mask density, `0..=255`.
pub vector_density: Option<u8>,
/// Vector mask feather, in pixels.
pub vector_feather: Option<f64>,
}
/// The real user mask of a layer with both a pixel and a vector mask.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct RealMask {
/// Flags, as [`MaskData::flags`].
pub flags: u8,
/// Value outside the rectangle (0 or 255).
pub default_color: u8,
/// Top, left, bottom, right.
pub rect: [i32; 4],
}
/// A layer record's mask data: 20 bytes for a lone mask (two of them
/// padding), 36 with the real user mask, then the parameters when
/// [`MaskData::flags`] has bit 4. The real mask comes before the
/// parameters, as Photoshop writes them (not as the specification lists
/// them).
#[derive(Clone, Debug, PartialEq)]
pub struct MaskData {
/// Top, left, bottom, right of the mask's pixels.
pub rect: [i32; 4],
/// Value outside the rectangle (0 or 255).
pub default_color: u8,
/// Bit 0 position relative to layer, bit 1 disabled, bit 2 invert
/// (obsolete), bit 3 rendered from other data, bit 4 has parameters.
pub flags: u8,
/// Density and feather.
pub params: Option<MaskParams>,
/// The real user mask.
pub real: Option<RealMask>,
/// Bytes after the fields, as the file had them (padding, or what
/// another writer added), written back unchanged.
pub tail: Vec<u8>,
}
/// An additional layer information block (document level or per layer).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct TaggedBlock {
/// `8BIM` or `8B64` (blocks with `padding: None` are written with
/// Photoshop's: `8B64` in large documents for keys with 64-bit
/// lengths).
pub signature: [u8; 4],
/// The block's key (`luni`, `lfx2`, `TySh`, …).
pub key: [u8; 4],
/// The block's data: the bytes its length covers (inside layer records
/// Photoshop counts the padding, so it ends with up to three zeros).
pub data: Vec<u8>,
/// Bytes written after the data, when they differ from what Photoshop
/// writes (other writers' padding, stray bytes before the next block);
/// `None` writes Photoshop's: zeros to a multiple of four bytes,
/// counted in the length inside layer records. Code that changes
/// `data` sets this to `None`.
pub padding: Option<Vec<u8>>,
/// The length field counts `padding` (only used with `Some` padding).
pub length_includes_padding: bool,
}
impl TaggedBlock {
/// A new `8BIM` block.
pub fn new(key: &[u8; 4], data: Vec<u8>) -> TaggedBlock {
TaggedBlock {
signature: *b"8BIM",
key: *key,
data,
padding: None,
length_includes_padding: false,
}
}
}
/// A layer record and its channels' image data.
#[derive(Clone, Debug, PartialEq)]
pub struct LayerRecord {
/// Top, left, bottom, right of the layer's pixels.
pub rect: [i32; 4],
/// Channel data, in the record's channel order.
pub channels: Vec<Channel>,
/// Blend mode key (`norm`, `mul `, …).
pub blend: [u8; 4],
/// Opacity, `0..=255`.
pub opacity: u8,
/// 0 base, 1 clipped to the layer below.
pub clipping: u8,
/// Bit 0 transparency protected, bit 1 hidden, bit 3 bit 4 is
/// meaningful, bit 4 pixel data irrelevant to appearance.
pub flags: u8,
/// The byte after the flags (normally 0).
pub filler: u8,
/// Mask data.
pub mask: Option<MaskData>,
/// Blending ranges, as stored (empty when absent).
pub blend_ranges: Vec<u8>,
/// The Pascal name (MacRoman), without its length byte.
pub name: Vec<u8>,
/// Additional layer information, in file order.
pub tagged: Vec<TaggedBlock>,
/// Bytes the record's extra data held that were not understood
/// (written back unchanged after the tagged blocks).
pub extra_tail: Vec<u8>,
/// Zero bytes after the name. Values below 4 stand for Photoshop's
/// padding (the name and its length byte to a multiple of four bytes),
/// recomputed on write so renamed and new records need not set it; a
/// name its writer padded otherwise keeps its padding plus 4, so it
/// writes back as it was.
pub name_padding: usize,
}
impl LayerRecord {
/// The layer's pixel rectangle (empty when its edges are reversed).
pub fn rect(&self) -> IRect {
let [top, left, bottom, right] = self.rect;
let size = |from: i32, to: i32| (i64::from(to) - i64::from(from)).clamp(0, 1 << 30) as i32;
IRect::new(left, top, size(left, right), size(top, bottom))
}
/// The first block with a key.
pub fn block(&self, key: &[u8; 4]) -> Option<&TaggedBlock> {
self.tagged.iter().find(|b| &b.key == key)
}
/// The first block with a key, to change.
pub fn block_mut(&mut self, key: &[u8; 4]) -> Option<&mut TaggedBlock> {
self.tagged.iter_mut().find(|b| &b.key == key)
}
/// Replaces the data of the first block with a key, adding the block
/// at the end when the record has none.
pub fn set_block(&mut self, key: &[u8; 4], data: Vec<u8>) {
match self.block_mut(key) {
Some(b) => {
b.data = data;
b.padding = None;
}
None => self.tagged.push(TaggedBlock::new(key, data)),
}
}
/// Removes every block with a key.
pub fn remove_block(&mut self, key: &[u8; 4]) {
self.tagged.retain(|b| &b.key != key);
}
/// The channel with an id.
pub fn channel(&self, id: i16) -> Option<&Channel> {
self.channels.iter().find(|c| c.id == id)
}
}
/// The layer records.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct LayerInfo {
/// The layer count was stored negative: the merged image's first alpha
/// channel holds its transparency.
pub merged_alpha: bool,
/// Records, bottom layer first.
pub records: Vec<LayerRecord>,
}
/// The layer and mask information section.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct LayerSection {
/// The layers.
pub info: LayerInfo,
/// The document-level block the layers are stored in (`Lr16`, `Lr32`)
/// instead of the section's own layer info; `None` for the section.
pub info_key: Option<[u8; 4]>,
/// The global layer mask info, as stored (without its length).
pub global_mask: Option<Vec<u8>>,
/// Document-level tagged blocks, in file order. When `info_key` is
/// set, the block with that key is here with empty data, marking where
/// [`LayerSection::info`] is written.
pub tagged: Vec<TaggedBlock>,
/// Bytes at the end of the section that were not understood (written
/// back unchanged).
pub tail: Vec<u8>,
/// Zero bytes after the layer info. Values below 4 stand for
/// Photoshop's padding (the section's layer info to a multiple of four
/// bytes, none inside an `Lr16`/`Lr32` block), recomputed on write; a
/// layer info its writer padded otherwise keeps its padding plus 4, so
/// it writes back as it was.
pub info_padding: usize,
}
impl LayerSection {
/// The first document-level block with a key.
pub fn block(&self, key: &[u8; 4]) -> Option<&TaggedBlock> {
self.tagged.iter().find(|b| &b.key == key)
}
/// Whether the section holds nothing (files without layers may store
/// no section at all).
pub fn is_empty(&self) -> bool {
self.info.records.is_empty()
&& !self.info.merged_alpha
&& self.info_key.is_none()
&& self.global_mask.is_none()
&& self.tagged.is_empty()
&& self.tail.is_empty()
&& self.info_padding < ESCAPED
}
}
/// The merged image data. A file that ends before it reads as `Raw` with
/// no bytes, which writes back as nothing.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct ImageData {
/// How it is compressed.
pub compression: Compression,
/// Every channel's compressed samples, planar, as stored (after the
/// two-byte compression code; RLE row counts included).
pub bytes: Vec<u8>,
}
/// A file, split into its parts.
#[derive(Clone, Debug, PartialEq)]
pub struct PsdFile {
/// The header.
pub header: Header,
/// Color mode data (an indexed file's palette, duotone curves), as
/// stored.
pub color_mode_data: Vec<u8>,
/// Image resources, in file order.
pub resources: Vec<Resource>,
/// Layers, masks, and document-level blocks.
pub layers: LayerSection,
/// The merged image.
pub image: ImageData,
}
impl PsdFile {
/// The first image resource with an id.
pub fn resource(&self, id: u16) -> Option<&Resource> {
self.resources.iter().find(|r| r.id == id)
}
}
/// Splits a `.psd` or `.psb` file into its parts.
pub fn read(bytes: &[u8]) -> Result<PsdFile> {
read::file(bytes)
}
/// Joins a file's parts back into bytes; an unedited file comes out as it
/// was read.
pub fn write(file: &PsdFile) -> Vec<u8> {
write::file(file)
}
/// Keys whose blocks have 64-bit lengths in large documents.
const LARGE_KEYS: [&[u8; 4]; 13] = [
b"LMsk", b"Lr16", b"Lr32", b"Layr", b"Mt16", b"Mt32", b"Mtrn", b"Alph", b"FMsk", b"lnk2",
b"FEid", b"FXid", b"PxSD",
];
/// Keys some readers (psd-tools) also take as 64-bit in large documents;
/// new blocks with them, and with [`LARGE_KEYS`], are signed `8B64` there
/// so every reader agrees, as recent Photoshop versions write them.
const MAYBE_LARGE_KEYS: [&[u8; 4]; 8] = [
b"lnk3", b"lnkE", b"FELS", b"pths", b"extd", b"extn", b"cinf", b"artd",
];
/// The layer-info blocks of 16- and 32-bit documents.
const LAYER_INFO_KEYS: [&[u8; 4]; 2] = [b"Lr16", b"Lr32"];
/// Added to a padding count the file departs from Photoshop's layout
/// with ([`LayerRecord::name_padding`], [`LayerSection::info_padding`]).
const ESCAPED: usize = 4;
/// Whether a block's length field is 64 bits.
fn is_large(signature: &[u8; 4], key: &[u8; 4], psb: bool) -> bool {
signature == b"8B64" || (psb && LARGE_KEYS.contains(&key))
}
/// The signature blocks without kept padding are written with.
fn writer_signature(key: &[u8; 4], psb: bool) -> [u8; 4] {
if psb && (LARGE_KEYS.contains(&key) || MAYBE_LARGE_KEYS.contains(&key)) {
*b"8B64"
} else {
*b"8BIM"
}
}
/// Whether bytes start with a tagged block signature.
fn is_block_signature(bytes: &[u8]) -> bool {
bytes.starts_with(b"8BIM") || bytes.starts_with(b"8B64")
}
/// Zeros that bring `len` bytes to a multiple of four.
fn pad4(len: usize) -> usize {
(4 - len % 4) % 4
}
/// Where a block sits, which decides the padding Photoshop gives it.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Level {
/// In a layer record: padded to four, the length counting the padding.
Record,
/// After the layer info: padded to four, the length not counting it.
Document,
}
fn corrupt(what: &str) -> PsdError {
PsdError::corrupt(what)
}
#[cfg(test)]
mod test;