SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Drawing sheets: paper sizes, orientation and the drawing border, as data in sheet millimetres.
//!
//! A [`Sheet`] is a paper size and an orientation; [`Sheet::size_mm`] gives its size as it lies, the
//! sheet border running round it. A [`DrawingBorderProfile`] is the rule for the drawing border
//! inside the sheet border: the margins between the two, the drawing border's line width, the grid
//! of reference fields with their labels, and the centring and trimming marks.
//! [`DrawingBorderProfile::validate`] checks a profile on its own, as when one is read, and
//! [`DrawingBorderProfile::layout`] works it out for one sheet, so a new size regrows it. Nothing
//! here is frozen geometry, saved in a design or drawn: a writer draws the [`SheetLayout`] later.
//!
//! Sheet coordinates are millimetres from the sheet's lower-left corner, x to the right and y up.
//! The drawing border's line is centred on [`SheetLayout::drawing_border`].
//!
//! [`DrawingBorderProfile::iso`] is the built-in profile, after ISO 5457: 10 mm margins all round,
//! a 0.7 mm drawing border, and 50 mm fields counted out from the sheet's centre lines, the corner
//! fields taking what is left. Rows are lettered from the top without I and O and columns numbered
//! from the left, on the sides [`LabelSides::Iso`] gives: the top and right of an A4 sheet, every
//! side of the others. The labels sit between the drawing border and the grid reference border,
//! 5 mm outside it. A centring mark runs across the whole margin, from the trimmed sheet's edge to
//! the drawing border, at each end of the sheet's centre lines, never into the drawing area.
//!
//! The rest of ISO 5457's border is a choice in the profile: the 20 mm filing margin on the left,
//! for drawings that get bound; centring marks that start at the grid reference border and reach
//! inside the drawing border (10 mm in the standard's figure); and a trimming mark at each corner, outside the grid reference border, of
//! two overlapping 10 x 5 mm rectangles. The built-in profile leaves the trimming marks out, as
//! they take a lot of ink.
//!
//! Sizes: ISO 216 A0 to A5, Letter and Legal, ANSI A to F (ASME Y14.1), the architectural A to E
//! and E1, and custom sizes, finite, above 0 and at most [`MAX_SIDE_MM`] a side. Title blocks sit on
//! the drawing border ([`crate::title_block`]). The elongated ISO sizes and the extra centring marks a
//! sheet larger than A0 needs (one in the middle of each section to be filmed) are not here yet.
use serde::{Deserialize, Serialize};
use crate::Aabb2;
use crate::paper::MAX_LINE_MM;
/// The longest side a custom sheet may have, in millimetres: the paper scene's limit.
pub use crate::paper::MAX_SIDE_MM;
use solidcore_record::Vec2;
/// The most fields an equal division may cut each way.
pub const MAX_EQUAL_FIELDS: u32 = 200;
/// ISO 5457's filing margin: the left margin of a drawing that gets bound.
pub const FILING_MARGIN_MM: f64 = 20.0;
const MIN_FIELD_MM: f64 = 1.0;
const MAX_FIELD_MM: f64 = 1000.0;
/// The smallest drawing space the margins may leave, each way.
const MIN_DRAWING_SPACE_MM: f64 = 1.0;
/// A corner field shorter than this joins its neighbour, so rounding never leaves a sliver.
const SLIVER_MM: f64 = 1e-9;
const INCH: f64 = 25.4;
/// A standard paper size.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PaperSize {
A0,
A1,
A2,
A3,
A4,
A5,
Letter,
Legal,
AnsiA,
AnsiB,
AnsiC,
AnsiD,
AnsiE,
AnsiF,
ArchA,
ArchB,
ArchC,
ArchD,
ArchE,
ArchE1,
}
impl PaperSize {
pub const ALL: [PaperSize; 20] = {
use PaperSize::*;
[A0, A1, A2, A3, A4, A5, Letter, Legal, AnsiA, AnsiB, AnsiC, AnsiD, AnsiE, AnsiF, ArchA, ArchB, ArchC, ArchD, ArchE, ArchE1]
};
/// The short and the long side, in millimetres (the US sizes from their inches).
pub fn sides_mm(self) -> (f64, f64) {
use PaperSize::*;
let inches = |short: f64, long: f64| (short * INCH, long * INCH);
match self {
A0 => (841.0, 1189.0),
A1 => (594.0, 841.0),
A2 => (420.0, 594.0),
A3 => (297.0, 420.0),
A4 => (210.0, 297.0),
A5 => (148.0, 210.0),
Letter | AnsiA => inches(8.5, 11.0),
Legal => inches(8.5, 14.0),
AnsiB => inches(11.0, 17.0),
AnsiC => inches(17.0, 22.0),
AnsiD => inches(22.0, 34.0),
AnsiE => inches(34.0, 44.0),
AnsiF => inches(28.0, 40.0),
ArchA => inches(9.0, 12.0),
ArchB => inches(12.0, 18.0),
ArchC => inches(18.0, 24.0),
ArchD => inches(24.0, 36.0),
ArchE => inches(36.0, 48.0),
ArchE1 => inches(30.0, 42.0),
}
}
}
/// A sheet's size: a standard one or any other.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub enum SheetSize {
Standard(PaperSize),
/// The two sides in either order; the orientation decides which lies across.
Custom {
sides_mm: [f64; 2],
},
}
/// Which way the sheet lies. Landscape puts the long side across.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Orientation {
#[default]
Landscape,
Portrait,
}
/// One sheet: its size and the way it lies (landscape when not given).
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Sheet {
pub size: SheetSize,
#[serde(default)]
pub orientation: Orientation,
}
/// The distances from the sheet border to the drawing border, in millimetres.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Margins {
pub left_mm: f64,
pub right_mm: f64,
pub top_mm: f64,
pub bottom_mm: f64,
}
impl Margins {
/// Left, right, top and bottom.
fn sides(self) -> [f64; 4] {
[self.left_mm, self.right_mm, self.top_mm, self.bottom_mm]
}
}
/// How the drawing border is cut into reference fields. Externally tagged (`"none"`,
/// `{"from_centre": {...}}`), as serde ignores extra fields on an internally tagged unit variant.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub enum GridRule {
/// No reference fields.
None,
/// Fields of `field_mm` counted out from the sheet's centre lines, the corner fields taking
/// what is left (ISO 5457, with 50 mm). Each way the larger half sets the count `n` (its
/// length over `field_mm`, rounded, at least 1), and each half has `n` fields, or fewer where
/// it is shorter.
FromCentre { field_mm: f64 },
/// The drawing border cut into equal fields.
Equal { columns: u32, rows: u32 },
}
/// Sides of the drawing border.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Sides {
pub top: bool,
pub bottom: bool,
pub left: bool,
pub right: bool,
}
impl Sides {
pub const ALL: Sides = Sides { top: true, bottom: true, left: true, right: true };
}
/// Which sides of the drawing border carry the field labels: a rule for any sheet, so a profile
/// made for one size labels another correctly.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub enum LabelSides {
/// ISO 5457's: the top and right of an A4 sheet (either way), every side of the others.
Iso,
/// The same sides on every sheet.
Fixed(Sides),
}
impl LabelSides {
/// The sides labelled on `sheet`.
pub fn on(self, sheet: &Sheet) -> Sides {
match self {
LabelSides::Iso if matches!(sheet.size, SheetSize::Standard(PaperSize::A4)) => {
Sides { top: true, bottom: false, left: false, right: true }
}
LabelSides::Iso => Sides::ALL,
LabelSides::Fixed(sides) => sides,
}
}
}
/// The rule for a drawing border and the marks around it: worked out for each sheet by
/// [`DrawingBorderProfile::layout`].
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DrawingBorderProfile {
pub margins: Margins,
/// ISO 5457's filing margin: when on, the left margin is [`FILING_MARGIN_MM`] in place of
/// `margins.left_mm`, which is kept for when it's off again. Off when not given.
#[serde(default)]
pub filing_margin: bool,
/// The drawing border's line width; the centring marks are drawn in it too.
pub drawing_border_line_mm: f64,
pub grid: GridRule,
/// Row letters skip I and O (they read as 1 and 0).
pub skip_i_and_o: bool,
pub label_sides: LabelSides,
/// How far outside the drawing border the grid reference border runs; the labels sit between
/// the two.
pub grid_border_mm: f64,
/// How far each centring mark reaches inside the drawing border, 0 to stop it on the drawing
/// border, at most [`MAX_SIDE_MM`] (`None`: no centring marks).
pub centring_mark_mm: Option<f64>,
/// Where each centring mark starts outside the drawing border. The trimmed sheet's edge when not
/// given.
#[serde(default)]
pub centring_mark_start: CentringMarkStart,
/// The trimming mark's rectangles: their length along the sheet border, at most
/// [`MAX_SIDE_MM`], and their width into the sheet, which must leave them outside the grid
/// reference border (`None`: no trimming marks).
pub trimming_mark_mm: Option<[f64; 2]>,
}
/// Where a centring mark starts, outside the drawing border.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CentringMarkStart {
/// The trimmed sheet's edge, so the mark runs across the whole margin (the built-in sheet's).
#[default]
SheetEdge,
/// The grid reference border, as ISO 5457's figure 5 draws it.
GridBorder,
}
/// One reference field along its axis: `from_mm < to_mm` in sheet coordinates.
#[derive(Clone, Debug, PartialEq)]
pub struct Field {
pub from_mm: f64,
pub to_mm: f64,
pub label: String,
}
/// A sheet's drawing border and the marks around it, worked out: what a writer draws.
#[derive(Clone, Debug, PartialEq)]
pub struct SheetLayout {
pub sheet_border: Aabb2,
pub drawing_border: Aabb2,
pub drawing_border_line_mm: f64,
/// Left to right, numbered from 1.
pub columns: Vec<Field>,
/// Top to bottom, lettered from A.
pub rows: Vec<Field>,
/// The sides labelled on this sheet.
pub label_sides: Sides,
pub grid_border: Aabb2,
/// Bottom, top, left and right: each from the grid reference border to the drawing border, or
/// as far inside it as the profile asks.
pub centring_marks: Vec<[Vec2; 2]>,
/// Filled rectangles, two at each corner of the sheet.
pub trimming_marks: Vec<Aabb2>,
}
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("drawing sheet: {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)) }
}
impl Sheet {
pub fn standard(size: PaperSize, orientation: Orientation) -> Sheet {
Sheet { size: SheetSize::Standard(size), orientation }
}
/// The sheet's width and height as it lies.
pub fn size_mm(&self) -> Result<Vec2> {
let (short, long) = match self.size {
SheetSize::Standard(size) => size.sides_mm(),
SheetSize::Custom { sides_mm: [a, b] } => {
for side in [a, b] {
require(side.is_finite() && side > 0.0 && side <= MAX_SIDE_MM, "a custom side is finite, above 0 and at most 5000 mm")?;
}
(a.min(b), a.max(b))
}
};
Ok(match self.orientation {
Orientation::Landscape => Vec2::new(long, short),
Orientation::Portrait => Vec2::new(short, long),
})
}
}
impl DrawingBorderProfile {
/// The built-in drawing border, after ISO 5457, for a sheet of any size (the module's notes
/// say how it follows the standard).
pub fn iso() -> DrawingBorderProfile {
DrawingBorderProfile {
margins: Margins { left_mm: 10.0, right_mm: 10.0, top_mm: 10.0, bottom_mm: 10.0 },
filing_margin: false,
drawing_border_line_mm: 0.7,
grid: GridRule::FromCentre { field_mm: 50.0 },
skip_i_and_o: true,
label_sides: LabelSides::Iso,
grid_border_mm: 5.0,
centring_mark_mm: Some(0.0),
centring_mark_start: CentringMarkStart::SheetEdge,
trimming_mark_mm: None,
}
}
/// The margins as laid out: `margins`, with the filing margin on the left when it's on.
fn laid_out_margins(&self) -> Margins {
let left_mm = if self.filing_margin { FILING_MARGIN_MM } else { self.margins.left_mm };
Margins { left_mm, ..self.margins }
}
/// Checks what doesn't depend on the sheet: call it when a profile is read. [`Self::layout`]
/// calls it too.
pub fn validate(&self) -> Result<()> {
// Every margin as given, the left one too while the filing margin stands in for it, so
// turning the filing margin off never brings back a bad value.
for margin in self.margins.sides() {
require(margin.is_finite() && (0.0..=MAX_SIDE_MM).contains(&margin), "a margin is finite and 0 to 5000 mm")?;
}
let line = self.drawing_border_line_mm;
require(line.is_finite() && line > 0.0 && line <= MAX_LINE_MM, "the drawing border's line is above 0 and at most 10 mm wide")?;
match self.grid {
GridRule::None => {}
GridRule::FromCentre { field_mm } => {
require(field_mm.is_finite() && (MIN_FIELD_MM..=MAX_FIELD_MM).contains(&field_mm), "a field is 1 to 1000 mm long")?
}
GridRule::Equal { columns, rows } => {
let counts = 1..=MAX_EQUAL_FIELDS;
require(counts.contains(&columns) && counts.contains(&rows), "an equal division has 1 to 200 fields each way")?
}
}
// The grid reference border lies in the margins, and the trimming marks between it and the
// sheet border (ISO 5457 4.5), so the narrowest margin laid out bounds both.
let narrowest = self.laid_out_margins().sides().into_iter().fold(f64::INFINITY, f64::min);
let g = self.grid_border_mm;
require(g.is_finite() && g >= 0.0 && g <= narrowest, "the grid reference border lies between the sheet border and the drawing border")?;
if let Some(reach) = self.centring_mark_mm {
let fits = reach.is_finite() && (0.0..=MAX_SIDE_MM).contains(&reach);
require(fits, "a centring mark ends on the drawing border or at most 5000 mm inside it")?;
// Else it would start and end on the drawing border.
let outside = match self.centring_mark_start {
CentringMarkStart::SheetEdge => narrowest,
CentringMarkStart::GridBorder => g,
};
require(outside > 0.0 || reach > 0.0, "a centring mark needs room outside the drawing border to start from, or a reach inside it")?;
}
if let Some([length, width]) = self.trimming_mark_mm {
let fits = length.is_finite() && length <= MAX_SIDE_MM && width > 0.0 && width <= length;
require(fits, "a trimming mark is above 0, at most 5000 mm long and no wider than it is long")?;
require(width <= narrowest - g, "a trimming mark lies between the sheet border and the grid reference border")?;
}
Ok(())
}
/// The drawing border and the marks around it on `sheet`.
pub fn layout(&self, sheet: &Sheet) -> Result<SheetLayout> {
self.validate()?;
let size = sheet.size_mm()?;
let m = self.laid_out_margins();
let drawing_border = Aabb2 { min: Vec2::new(m.left_mm, m.bottom_mm), max: Vec2::new(size.x - m.right_mm, size.y - m.top_mm) };
let space = drawing_border.size();
require(space.x >= MIN_DRAWING_SPACE_MM && space.y >= MIN_DRAWING_SPACE_MM, "the margins leave no drawing space")?;
let (across, down) = match self.grid {
GridRule::None => (vec![], vec![]),
GridRule::FromCentre { field_mm } => (
from_centre(drawing_border.min.x, drawing_border.max.x, size.x / 2.0, field_mm)?,
from_centre(drawing_border.min.y, drawing_border.max.y, size.y / 2.0, field_mm)?,
),
GridRule::Equal { columns, rows } => {
(equal(drawing_border.min.x, drawing_border.max.x, columns), equal(drawing_border.min.y, drawing_border.max.y, rows))
}
};
let columns = fields(&across, |i| (i + 1).to_string());
// Rows run top to bottom: the edges are in rising y, so the top row comes last.
let mut rows = fields(&down, |_| String::new());
rows.reverse();
for (i, row) in rows.iter_mut().enumerate() {
row.label = letters(i, self.skip_i_and_o);
}
let sheet_border = Aabb2 { min: Vec2::ZERO, max: size };
let grid_border = drawing_border.inflated(self.grid_border_mm);
let start = match self.centring_mark_start {
CentringMarkStart::SheetEdge => sheet_border,
CentringMarkStart::GridBorder => grid_border,
};
let centring_marks = match self.centring_mark_mm {
Some(reach) => centring_marks(start, drawing_border, size, reach)?,
None => Vec::new(),
};
let trimming_marks = match self.trimming_mark_mm {
Some(mark) => trimming_marks(size, mark)?,
None => Vec::new(),
};
Ok(SheetLayout {
sheet_border,
drawing_border,
drawing_border_line_mm: self.drawing_border_line_mm,
columns,
rows,
label_sides: self.label_sides.on(sheet),
grid_border,
centring_marks,
trimming_marks,
})
}
}
/// The four centring marks: on the sheet's centre lines, from the edges of `start` to `reach`
/// inside the drawing border, which must not take them past the centre.
fn centring_marks(start: Aabb2, drawing_border: Aabb2, size: Vec2, reach: f64) -> Result<Vec<[Vec2; 2]>> {
let (cx, cy) = (size.x / 2.0, size.y / 2.0);
let (lo, hi) = (drawing_border.min, drawing_border.max);
let room = (cx - lo.x).min(hi.x - cx).min(cy - lo.y).min(hi.y - cy);
require(reach <= room, "a centring mark stops at the sheet's centre lines")?;
Ok(vec![
[Vec2::new(cx, start.min.y), Vec2::new(cx, lo.y + reach)],
[Vec2::new(cx, start.max.y), Vec2::new(cx, hi.y - reach)],
[Vec2::new(start.min.x, cy), Vec2::new(lo.x + reach, cy)],
[Vec2::new(start.max.x, cy), Vec2::new(hi.x - reach, cy)],
])
}
/// The trimming marks: at each corner of the sheet, a rectangle `length` along each edge and
/// `width` into the sheet, the two overlapping in the corner.
fn trimming_marks(size: Vec2, [length, width]: [f64; 2]) -> Result<Vec<Aabb2>> {
// Any longer and the two marks on one edge would meet.
require(length <= size.x.min(size.y) / 2.0, "a trimming mark is at most half the sheet's shorter side long")?;
// The span `extent` long from one end of `0..side`, the far end when `far`.
let span = |far: bool, side: f64, extent: f64| if far { (side - extent, side) } else { (0.0, extent) };
let mut marks = Vec::with_capacity(8);
for (right, top) in [(false, false), (true, false), (false, true), (true, true)] {
for (across, up) in [(length, width), (width, length)] {
let ((x0, x1), (y0, y1)) = (span(right, size.x, across), span(top, size.y, up));
marks.push(Aabb2 { min: Vec2::new(x0, y0), max: Vec2::new(x1, y1) });
}
}
Ok(marks)
}
/// The field edges from `lo` to `hi`, in rising order, for fields of `field` out from `centre`.
fn from_centre(lo: f64, hi: f64, centre: f64, field: f64) -> Result<Vec<f64>> {
let (below, above) = (centre - lo, hi - centre);
require(below > SLIVER_MM && above > SLIVER_MM, "the sheet's centre lines cross the drawing border")?;
// At most MAX_SIDE_MM / MIN_FIELD_MM per half: a bounded count.
let n = (below.max(above) / field).round().max(1.0);
let count = |half: f64| n.min(((half - SLIVER_MM) / field).ceil()) as usize;
let (k_below, k_above) = (count(below), count(above));
let mut edges = Vec::with_capacity(k_below + k_above + 1);
edges.push(lo);
edges.extend((1..k_below).rev().map(|j| centre - j as f64 * field));
edges.push(centre);
edges.extend((1..k_above).map(|j| centre + j as f64 * field));
edges.push(hi);
Ok(edges)
}
/// The edges of `n` equal fields from `lo` to `hi`, ending exactly at `hi`.
fn equal(lo: f64, hi: f64, n: u32) -> Vec<f64> {
let step = (hi - lo) / f64::from(n);
(0..n).map(|i| lo + f64::from(i) * step).chain(std::iter::once(hi)).collect()
}
fn fields(edges: &[f64], label: impl Fn(usize) -> String) -> Vec<Field> {
edges
.windows(2)
.enumerate()
.filter_map(|(i, w)| match *w {
[from_mm, to_mm] => Some(Field { from_mm, to_mm, label: label(i) }),
_ => None,
})
.collect()
}
/// The row label for row `i` (0 is A): A to Z, then AA, AB and on (without I and O if asked).
pub fn letters(i: usize, skip_i_and_o: bool) -> String {
const ALL: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ";
const NO_I_O: &[u8] = b"ABCDEFGHJKLMNPQRSTUVWXYZ";
let alphabet = if skip_i_and_o { NO_I_O } else { ALL };
let base = alphabet.len();
let mut out = Vec::new();
// Bijective numbering: after the last letter comes AA, not BA.
let mut n = i.saturating_add(1);
while n > 0 {
n -= 1;
out.extend(alphabet.get(n % base).map(|&b| char::from(b)));
n /= base;
}
out.iter().rev().collect()
}
#[cfg(test)]
#[path = "drawing_sheet_tests.rs"]
mod tests;