Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

10.4 KB
Raw Blame
//! Title blocks: the block of cells that identifies a drawing and what its sheet documents, as
//! data in sheet millimetres.
//!
//! A [`TitleBlock`] is a definition: its size, its two line widths and its cells. Each [`Cell`] is
//! a rectangle measured from the block's lower-right corner (x at most 0, y at least 0), with a
//! label and a value: text from cell content ([`crate::cell`]), or the projection symbol. The block
//! sits on the drawing border's lower-right corner, so one definition serves every sheet it fits.
//! [`TitleBlock::validate`] checks a definition on its own, as when one is read, and
//! [`TitleBlock::layout`] places it on one sheet by the cell text rule: each cell's rectangle, where
//! its label goes and the box its value goes in. Values are set in their boxes once the paper scene
//! has text; nothing here is saved or drawn yet.
//!
//! The outline is drawn `outline_line_mm` wide and the lines between cells `cell_line_mm`, each
//! centred on its edge. The block's right and bottom edges lie on the drawing border, whose line is
//! centred there too. A cell's text is padded from the inner edge of its lines and of the border's
//! line, wherever that reaches, and its descenders never reach a line (the cell text rule), so no
//! line covers it.

use serde::{Deserialize, Serialize};

use crate::Aabb2;
use crate::cell::{self, Content, Fit, HAlign};
use crate::drawing_sheet::SheetLayout;
use crate::paper::MAX_LINE_MM;
use solidcore_record::Vec2;

/// The most cells a block may have.
pub const MAX_CELLS: usize = 64;
const MIN_BLOCK_SIDE_MM: f64 = 1.0;
const MAX_BLOCK_SIDE_MM: f64 = 1000.0;
const MAX_NAME_BYTES: usize = 64;

/// A title block's definition.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TitleBlock {
    /// The block's width and height.
    pub size_mm: Vec2,
    pub outline_line_mm: f64,
    pub cell_line_mm: f64,
    pub cells: Vec<Cell>,
}

/// One cell of a block.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Cell {
    /// Snake case, and no other cell of the block has it.
    pub name: String,
    /// `[x0, y0, x1, y1]` from the block's lower-right corner: `-width <= x0 < x1 <= 0` and
    /// `0 <= y0 < y1 <= height`.
    pub rect_mm: [f64; 4],
    /// None: the value has the whole cell.
    pub label: Option<Label>,
    pub kind: CellKind,
}

/// A cell's label, such as "Created by": one line at its top left.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Label {
    pub text: String,
    pub cap_mm: f64,
}

/// What a cell's value is. Externally tagged (`{"text": {...}}`, `"projection_symbol"`), as serde
/// ignores extra fields on an internally tagged unit variant.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub enum CellKind {
    Text(TextCell),
    /// The projection symbol, drawn from the drawing's projection (`drawing.projection`), which the
    /// views read too: never fixed in the block.
    ProjectionSymbol,
}

/// A text value: its content, its cap height, where its lines sit across the value box (left when
/// not given) and what it should fit (nothing when not given).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TextCell {
    pub content: Content,
    pub cap_mm: f64,
    #[serde(default)]
    pub align: HAlign,
    #[serde(default)]
    pub fit: Fit,
}

/// A block placed on one sheet: what a writer draws, before the values are set.
#[derive(Clone, Debug, PartialEq)]
pub struct TitleBlockLayout {
    pub outline: Aabb2,
    pub outline_line_mm: f64,
    pub cell_line_mm: f64,
    /// One for each of the definition's cells, in its order.
    pub cells: Vec<CellLayout>,
}

/// One cell placed on a sheet.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct CellLayout {
    pub rect: Aabb2,
    /// Where the label's baseline starts, when the cell has one.
    pub label_at: Option<Vec2>,
    pub value_box: Aabb2,
}

#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("title block: {0}")]
pub struct Invalid(pub &'static str);

type Result<T> = std::result::Result<T, Invalid>;

fn require(condition: bool, message: &'static str) -> Result<()> {
    if condition { Ok(()) } else { Err(Invalid(message)) }
}

/// A lowercase letter, then lowercase letters, digits and underscores: at most 64 in all.
fn is_snake_case(name: &str) -> bool {
    let mut bytes = name.bytes();
    name.len() <= MAX_NAME_BYTES
        && bytes.next().is_some_and(|b| b.is_ascii_lowercase())
        && bytes.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_')
}

/// Whether two rectangles share more than an edge.
fn overlap(a: Aabb2, b: Aabb2) -> bool {
    a.min.x < b.max.x && b.min.x < a.max.x && a.min.y < b.max.y && b.min.y < a.max.y
}

impl Cell {
    /// The cell's rectangle with the block's lower-right corner at `corner`.
    fn rect(&self, corner: Vec2) -> Aabb2 {
        let [x0, y0, x1, y1] = self.rect_mm;
        Aabb2 { min: corner + Vec2::new(x0, y0), max: corner + Vec2::new(x1, y1) }
    }

    /// The box its value goes in, in `inside`, the cell inside its lines.
    fn value_box(&self, inside: Aabb2) -> Aabb2 {
        cell::value_box(inside, self.label.as_ref().map(|label| label.cap_mm))
    }
}

impl TitleBlock {
    /// `cell`'s rectangle `rect` inside its lines: each side moved in by half the line drawn on it,
    /// the outline's on the block's edges and a cell line's inside the block.
    fn inside_lines(&self, cell: &Cell, rect: Aabb2) -> Aabb2 {
        let [x0, y0, x1, y1] = cell.rect_mm;
        let half = |on_outline: bool| if on_outline { self.outline_line_mm } else { self.cell_line_mm } / 2.0;
        let lower = Vec2::new(half(x0 == -self.size_mm.x), half(y0 == 0.0));
        let upper = Vec2::new(half(x1 == 0.0), half(y1 == self.size_mm.y));
        Aabb2 { min: rect.min + lower, max: rect.max - upper }
    }

    /// Each cell with the block's lower-right corner at `corner`, inside its lines and inside
    /// `clear` too when given (the drawing border's line's inner edge), checked by the cell text
    /// rule: room for a value below its label, and for one line of a text value.
    fn place_cells(&self, corner: Vec2, clear: Option<Aabb2>) -> Result<Vec<CellLayout>> {
        let place = |cell: &Cell| {
            let rect = cell.rect(corner);
            let inside = self.inside_lines(cell, rect);
            let inside = clear.map_or(inside, |clear| inside.intersection(&clear));
            let value_box = cell.value_box(inside);
            let room = value_box.size();
            require(room.x > 0.0 && room.y > 0.0, "a cell has room for its value below its label")?;
            if let CellKind::Text(text) = &cell.kind {
                let one_line = cell::place_lines(value_box, 1, text.cap_mm, text.cap_mm, text.align, false);
                require(matches!(one_line, Ok((_, None))), "a value's cap height is above 0 and one line of it fits its value box")?;
            }
            let label_at = cell.label.as_ref().map(|label| cell::label_at(inside, label.cap_mm));
            Ok(CellLayout { rect, label_at, value_box })
        };
        self.cells.iter().map(place).collect()
    }

    /// Checks a definition on its own, counting its cells first: call it when one is read. Its
    /// cells' room is checked with the corner at the origin and only the outline on its edges;
    /// [`Self::layout`] calls it too, and checks their room again where the block sits.
    pub fn validate(&self) -> Result<()> {
        require(self.cells.len() <= MAX_CELLS, "a title block has at most 64 cells")?;
        let Vec2 { x: width, y: height } = self.size_mm;
        let sides = MIN_BLOCK_SIDE_MM..=MAX_BLOCK_SIDE_MM;
        require(sides.contains(&width) && sides.contains(&height), "each side of a title block is 1 to 1000 mm")?;
        let lines = [self.outline_line_mm, self.cell_line_mm];
        require(lines.into_iter().all(|line| line > 0.0 && line <= MAX_LINE_MM), "a title block's lines are above 0 and at most 10 mm wide")?;
        for (i, cell) in self.cells.iter().enumerate() {
            let earlier = || self.cells.iter().take(i);
            require(is_snake_case(&cell.name), "a cell's name is snake case and at most 64 characters")?;
            require(earlier().all(|other| other.name != cell.name), "no two cells have the same name")?;
            let [x0, y0, x1, y1] = cell.rect_mm;
            require(-width <= x0 && x0 < x1 && x1 <= 0.0 && 0.0 <= y0 && y0 < y1 && y1 <= height, "a cell lies inside its block")?;
            let rect = cell.rect(Vec2::ZERO);
            require(earlier().all(|other| !overlap(other.rect(Vec2::ZERO), rect)), "no two cells overlap")?;
            if let Some(label) = &cell.label {
                require(label.cap_mm.is_finite() && label.cap_mm > 0.0, "a label's cap height is finite and above 0")?;
                cell::check_label(&label.text).map_err(|cell::Invalid(message)| Invalid(message))?;
            }
            if let CellKind::Text(text) = &cell.kind {
                text.content.validate().map_err(|cell::Invalid(message)| Invalid(message))?;
            }
        }
        self.place_cells(Vec2::ZERO, None)?;
        Ok(())
    }

    /// The block on the lower-right corner of `sheet`'s drawing border, which must hold it, each
    /// cell with room inside the border's line too.
    pub fn layout(&self, sheet: &SheetLayout) -> Result<TitleBlockLayout> {
        self.validate()?;
        let border = sheet.drawing_border;
        let (size, room) = (self.size_mm, border.size());
        let fits = border.min.is_finite() && border.max.is_finite() && size.x <= room.x && size.y <= room.y;
        require(fits, "a title block fits inside the drawing border")?;
        let corner = Vec2::new(border.max.x, border.min.y);
        // Checked again here: the border's line, centred on it, runs along the block's right and
        // bottom edges (and any other it reaches), and rounding at the real corner may take the
        // last of a cell's room.
        let cells = self.place_cells(corner, Some(border.inflated(-sheet.drawing_border_line_mm / 2.0)))?;
        Ok(TitleBlockLayout {
            outline: Aabb2 { min: corner - Vec2::new(size.x, 0.0), max: corner + Vec2::new(0.0, size.y) },
            outline_line_mm: self.outline_line_mm,
            cell_line_mm: self.cell_line_mm,
            cells,
        })
    }
}

#[cfg(test)]
#[path = "title_block_tests.rs"]
mod tests;