ppt_rs/core/
dimension.rs

1//! Flexible dimension types for position and size specification
2//!
3//! Supports multiple units: EMU, inches, centimeters, points, and ratio (0.0–1.0 of slide).
4//!
5//! # Examples
6//! ```
7//! use ppt_rs::core::Dimension;
8//!
9//! // Different ways to express the same position
10//! let d1 = Dimension::Emu(914400);
11//! let d2 = Dimension::Inches(1.0);
12//! let d3 = Dimension::Cm(2.54);
13//! let d4 = Dimension::Ratio(0.1); // 10% of reference (slide width or height)
14//!
15//! assert_eq!(d1.to_emu(9144000), 914400);
16//! assert_eq!(d2.to_emu(9144000), 914400);
17//! assert_eq!(d4.to_emu(9144000), 914400); // 10% of 10 inches
18//! ```
19
20/// Standard slide width in EMU (10 inches)
21pub const SLIDE_WIDTH_EMU: u32 = 9144000;
22/// Standard slide height in EMU (7.5 inches)
23pub const SLIDE_HEIGHT_EMU: u32 = 6858000;
24
25/// EMU per inch
26const EMU_PER_INCH: f64 = 914400.0;
27/// EMU per centimeter
28const EMU_PER_CM: f64 = 360000.0;
29/// EMU per point
30const EMU_PER_PT: f64 = 12700.0;
31
32/// A flexible dimension that can be expressed in multiple units.
33///
34/// All variants resolve to EMU (English Metric Units) at render time.
35/// `Ratio` is relative to a reference dimension (slide width for x/width, slide height for y/height).
36#[derive(Clone, Debug, PartialEq)]
37pub enum Dimension {
38    /// Absolute value in EMU (English Metric Units)
39    Emu(u32),
40    /// Value in inches (1 inch = 914400 EMU)
41    Inches(f64),
42    /// Value in centimeters (1 cm = 360000 EMU)
43    Cm(f64),
44    /// Value in points (1 pt = 12700 EMU)
45    Pt(f64),
46    /// Ratio of reference dimension (0.0–1.0). For x/width, reference is slide width; for y/height, slide height.
47    Ratio(f64),
48}
49
50impl Dimension {
51    /// Resolve to EMU given a reference dimension (used only for `Ratio`).
52    ///
53    /// For absolute units (Emu, Inches, Cm, Pt), `reference_emu` is ignored.
54    pub fn to_emu(&self, reference_emu: u32) -> u32 {
55        match self {
56            Dimension::Emu(v) => *v,
57            Dimension::Inches(v) => (v * EMU_PER_INCH) as u32,
58            Dimension::Cm(v) => (v * EMU_PER_CM) as u32,
59            Dimension::Pt(v) => (v * EMU_PER_PT) as u32,
60            Dimension::Ratio(r) => (r.clamp(0.0, 1.0) * reference_emu as f64) as u32,
61        }
62    }
63
64    /// Resolve X position or width to EMU (reference = slide width)
65    pub fn to_emu_x(&self) -> u32 {
66        self.to_emu(SLIDE_WIDTH_EMU)
67    }
68
69    /// Resolve Y position or height to EMU (reference = slide height)
70    pub fn to_emu_y(&self) -> u32 {
71        self.to_emu(SLIDE_HEIGHT_EMU)
72    }
73}
74
75/// Convenience: convert from u32 (treated as EMU)
76impl From<u32> for Dimension {
77    fn from(emu: u32) -> Self {
78        Dimension::Emu(emu)
79    }
80}
81
82/// Convenience: convert from f64 (treated as ratio if 0.0–1.0, else inches)
83/// This is intentionally NOT implemented to avoid ambiguity.
84/// Use the explicit constructors instead.
85
86/// Shorthand constructors for ergonomic API
87impl Dimension {
88    /// Create from inches
89    pub fn inches(v: f64) -> Self { Dimension::Inches(v) }
90    /// Create from centimeters
91    pub fn cm(v: f64) -> Self { Dimension::Cm(v) }
92    /// Create from points
93    pub fn pt(v: f64) -> Self { Dimension::Pt(v) }
94    /// Create from ratio (0.0–1.0 of slide dimension)
95    pub fn ratio(v: f64) -> Self { Dimension::Ratio(v) }
96    /// Create from EMU
97    pub fn emu(v: u32) -> Self { Dimension::Emu(v) }
98    /// Create from percentage (0–100) of slide dimension
99    pub fn percent(v: f64) -> Self { Dimension::Ratio(v / 100.0) }
100}
101
102/// A 2D position expressed in flexible dimensions.
103#[derive(Clone, Debug)]
104pub struct FlexPosition {
105    pub x: Dimension,
106    pub y: Dimension,
107}
108
109impl FlexPosition {
110    pub fn new(x: Dimension, y: Dimension) -> Self {
111        Self { x, y }
112    }
113
114    /// Resolve to (x_emu, y_emu) using standard slide dimensions
115    pub fn to_emu(&self) -> (u32, u32) {
116        (self.x.to_emu_x(), self.y.to_emu_y())
117    }
118
119    /// Resolve to (x_emu, y_emu) using custom slide dimensions
120    pub fn to_emu_with(&self, slide_width: u32, slide_height: u32) -> (u32, u32) {
121        (self.x.to_emu(slide_width), self.y.to_emu(slide_height))
122    }
123}
124
125/// A 2D size expressed in flexible dimensions.
126#[derive(Clone, Debug)]
127pub struct FlexSize {
128    pub width: Dimension,
129    pub height: Dimension,
130}
131
132impl FlexSize {
133    pub fn new(width: Dimension, height: Dimension) -> Self {
134        Self { width, height }
135    }
136
137    /// Resolve to (width_emu, height_emu) using standard slide dimensions
138    pub fn to_emu(&self) -> (u32, u32) {
139        (self.width.to_emu_x(), self.height.to_emu_y())
140    }
141
142    /// Resolve to (width_emu, height_emu) using custom slide dimensions
143    pub fn to_emu_with(&self, slide_width: u32, slide_height: u32) -> (u32, u32) {
144        (self.width.to_emu(slide_width), self.height.to_emu(slide_height))
145    }
146}
147
148#[cfg(test)]
149mod tests {
150    use super::*;
151
152    #[test]
153    fn test_emu_passthrough() {
154        assert_eq!(Dimension::Emu(914400).to_emu(0), 914400);
155    }
156
157    #[test]
158    fn test_inches_to_emu() {
159        assert_eq!(Dimension::Inches(1.0).to_emu(0), 914400);
160        assert_eq!(Dimension::Inches(0.5).to_emu(0), 457200);
161        assert_eq!(Dimension::Inches(10.0).to_emu(0), 9144000);
162    }
163
164    #[test]
165    fn test_cm_to_emu() {
166        assert_eq!(Dimension::Cm(2.54).to_emu(0), 914400);
167        assert_eq!(Dimension::Cm(1.0).to_emu(0), 360000);
168    }
169
170    #[test]
171    fn test_pt_to_emu() {
172        assert_eq!(Dimension::Pt(72.0).to_emu(0), 914400); // 72pt = 1 inch
173        assert_eq!(Dimension::Pt(1.0).to_emu(0), 12700);
174    }
175
176    #[test]
177    fn test_ratio_to_emu() {
178        // 10% of slide width (10 inches = 9144000 EMU) = 1 inch
179        assert_eq!(Dimension::Ratio(0.1).to_emu(SLIDE_WIDTH_EMU), 914400);
180        // 50% of slide width = 5 inches
181        assert_eq!(Dimension::Ratio(0.5).to_emu(SLIDE_WIDTH_EMU), 4572000);
182        // 100% of slide width = 10 inches
183        assert_eq!(Dimension::Ratio(1.0).to_emu(SLIDE_WIDTH_EMU), 9144000);
184        // 0% = 0
185        assert_eq!(Dimension::Ratio(0.0).to_emu(SLIDE_WIDTH_EMU), 0);
186    }
187
188    #[test]
189    fn test_ratio_clamped() {
190        // Values > 1.0 clamped to 1.0
191        assert_eq!(Dimension::Ratio(1.5).to_emu(SLIDE_WIDTH_EMU), 9144000);
192        // Values < 0.0 clamped to 0.0
193        assert_eq!(Dimension::Ratio(-0.5).to_emu(SLIDE_WIDTH_EMU), 0);
194    }
195
196    #[test]
197    fn test_percent() {
198        assert_eq!(Dimension::percent(50.0).to_emu(SLIDE_WIDTH_EMU), 4572000);
199        assert_eq!(Dimension::percent(10.0).to_emu(SLIDE_WIDTH_EMU), 914400);
200    }
201
202    #[test]
203    fn test_to_emu_x_y() {
204        let x = Dimension::Ratio(0.5);
205        let y = Dimension::Ratio(0.5);
206        assert_eq!(x.to_emu_x(), SLIDE_WIDTH_EMU / 2);
207        assert_eq!(y.to_emu_y(), SLIDE_HEIGHT_EMU / 2);
208    }
209
210    #[test]
211    fn test_flex_position() {
212        let pos = FlexPosition::new(Dimension::Inches(1.0), Dimension::Ratio(0.5));
213        let (x, y) = pos.to_emu();
214        assert_eq!(x, 914400);
215        assert_eq!(y, SLIDE_HEIGHT_EMU / 2);
216    }
217
218    #[test]
219    fn test_flex_size() {
220        let size = FlexSize::new(Dimension::Ratio(0.8), Dimension::Inches(2.0));
221        let (w, h) = size.to_emu();
222        assert_eq!(w, (SLIDE_WIDTH_EMU as f64 * 0.8) as u32);
223        assert_eq!(h, 914400 * 2);
224    }
225
226    #[test]
227    fn test_flex_position_custom_slide() {
228        let custom_w = 12192000_u32; // 13.33 inches (widescreen)
229        let custom_h = 6858000_u32;
230        let pos = FlexPosition::new(Dimension::Ratio(0.5), Dimension::Ratio(0.5));
231        let (x, y) = pos.to_emu_with(custom_w, custom_h);
232        assert_eq!(x, custom_w / 2);
233        assert_eq!(y, custom_h / 2);
234    }
235
236    #[test]
237    fn test_from_u32() {
238        let d: Dimension = 914400_u32.into();
239        assert_eq!(d, Dimension::Emu(914400));
240    }
241
242    #[test]
243    fn test_shorthand_constructors() {
244        assert_eq!(Dimension::inches(1.0), Dimension::Inches(1.0));
245        assert_eq!(Dimension::cm(2.54), Dimension::Cm(2.54));
246        assert_eq!(Dimension::pt(72.0), Dimension::Pt(72.0));
247        assert_eq!(Dimension::ratio(0.5), Dimension::Ratio(0.5));
248        assert_eq!(Dimension::emu(914400), Dimension::Emu(914400));
249    }
250}
ppt_rs/core/dimension.rs

ppt_rs/core/
dimension.rs
