Skip to main content

pillow_rs/ops/
array.rs

1//! Pillow-compatible array-interface descriptor resolution.
2//!
3//! Host bindings extract `__array_interface__` fields and pass only plain
4//! shape/type/mode values here. Dtype inference and dimensional policy belong
5//! to core so Python and JavaScript cannot drift.
6
7use crate::error::PilError;
8use crate::image::Image;
9
10/// Resolved Pillow image and raw-decoder layout for an array descriptor.
11#[derive(Clone, Debug, Eq, PartialEq)]
12pub struct ArrayLayout {
13    /// Public Pillow image mode.
14    pub mode: String,
15    /// Pillow raw decoder mode.
16    pub raw_mode: String,
17    /// Image width.
18    pub width: usize,
19    /// Image height.
20    pub height: usize,
21    /// Number of array dimensions.
22    pub dimensions: usize,
23    /// Whether explicit mode changes the inferred dtype interpretation.
24    pub mode_reinterprets_dtype: bool,
25}
26
27struct TypeMapEntry {
28    shape_tail: &'static [usize],
29    typestr: &'static str,
30    mode: &'static str,
31    raw_mode: &'static str,
32    color_modes: &'static [&'static str],
33}
34
35const TYPE_MAP: &[TypeMapEntry] = &[
36    TypeMapEntry {
37        shape_tail: &[],
38        typestr: "|b1",
39        mode: "1",
40        raw_mode: "1;8",
41        color_modes: &[],
42    },
43    TypeMapEntry {
44        shape_tail: &[],
45        typestr: "|u1",
46        mode: "L",
47        raw_mode: "L",
48        color_modes: &["P"],
49    },
50    TypeMapEntry {
51        shape_tail: &[],
52        typestr: "|i1",
53        mode: "I",
54        raw_mode: "I;8",
55        color_modes: &[],
56    },
57    TypeMapEntry {
58        shape_tail: &[],
59        typestr: "<u2",
60        mode: "I",
61        raw_mode: "I;16",
62        color_modes: &[],
63    },
64    TypeMapEntry {
65        shape_tail: &[],
66        typestr: ">u2",
67        mode: "I",
68        raw_mode: "I;16B",
69        color_modes: &[],
70    },
71    TypeMapEntry {
72        shape_tail: &[],
73        typestr: "<i2",
74        mode: "I",
75        raw_mode: "I;16S",
76        color_modes: &[],
77    },
78    TypeMapEntry {
79        shape_tail: &[],
80        typestr: ">i2",
81        mode: "I",
82        raw_mode: "I;16BS",
83        color_modes: &[],
84    },
85    TypeMapEntry {
86        shape_tail: &[],
87        typestr: "<u4",
88        mode: "I",
89        raw_mode: "I;32",
90        color_modes: &[],
91    },
92    TypeMapEntry {
93        shape_tail: &[],
94        typestr: ">u4",
95        mode: "I",
96        raw_mode: "I;32B",
97        color_modes: &[],
98    },
99    TypeMapEntry {
100        shape_tail: &[],
101        typestr: "<i4",
102        mode: "I",
103        raw_mode: "I",
104        color_modes: &[],
105    },
106    TypeMapEntry {
107        shape_tail: &[],
108        typestr: ">i4",
109        mode: "I",
110        raw_mode: "I;32BS",
111        color_modes: &[],
112    },
113    TypeMapEntry {
114        shape_tail: &[],
115        typestr: "<f4",
116        mode: "F",
117        raw_mode: "F",
118        color_modes: &[],
119    },
120    TypeMapEntry {
121        shape_tail: &[],
122        typestr: ">f4",
123        mode: "F",
124        raw_mode: "F;32BF",
125        color_modes: &[],
126    },
127    TypeMapEntry {
128        shape_tail: &[],
129        typestr: "<f8",
130        mode: "F",
131        raw_mode: "F;64F",
132        color_modes: &[],
133    },
134    TypeMapEntry {
135        shape_tail: &[],
136        typestr: ">f8",
137        mode: "F",
138        raw_mode: "F;64BF",
139        color_modes: &[],
140    },
141    TypeMapEntry {
142        shape_tail: &[2],
143        typestr: "|u1",
144        mode: "LA",
145        raw_mode: "LA",
146        color_modes: &["La", "PA"],
147    },
148    TypeMapEntry {
149        shape_tail: &[3],
150        typestr: "|u1",
151        mode: "RGB",
152        raw_mode: "RGB",
153        color_modes: &["YCbCr", "LAB", "HSV"],
154    },
155    TypeMapEntry {
156        shape_tail: &[4],
157        typestr: "|u1",
158        mode: "RGBA",
159        raw_mode: "RGBA",
160        color_modes: &["RGBa", "RGBX", "CMYK"],
161    },
162];
163
164/// Resolve Pillow's array-interface type key, mode, raw mode, size, and
165/// dimensional limit.
166///
167/// # Errors
168///
169/// Returns Pillow-compatible [`PilError::TypeError`] for unsupported type keys
170/// and [`PilError::ValueError`] for excessive dimensions.
171pub fn resolve_array_layout(
172    shape: &[usize],
173    typestr: &str,
174    explicit_mode: Option<&str>,
175) -> Result<ArrayLayout, PilError> {
176    let shape_tail = shape.get(2..).unwrap_or_default();
177    let Some(entry) = TYPE_MAP
178        .iter()
179        .find(|entry| entry.shape_tail == shape_tail && entry.typestr == typestr)
180    else {
181        return Err(PilError::TypeError(format!(
182            "Cannot handle this data type: {}, {typestr}",
183            format_typekey_shape(shape_tail)
184        )));
185    };
186
187    let mode = explicit_mode.unwrap_or(entry.mode);
188    let dimensions = shape.len();
189    let maximum_dimensions = match mode {
190        "1" | "L" | "I" | "P" | "F" => 2,
191        "RGB" => 3,
192        _ => 4,
193    };
194    if dimensions > maximum_dimensions {
195        return Err(PilError::ValueError(format!(
196            "Too many dimensions: {dimensions} > {maximum_dimensions}."
197        )));
198    }
199
200    let (width, height) = match shape {
201        [length] => (1, *length),
202        [height, width, ..] => (*width, *height),
203        [] => {
204            return Err(PilError::IndexError("tuple index out of range".to_string()));
205        }
206    };
207    // Pillow's ``fromarray`` resolves the image size in ``frombuffer`` before
208    // it asks an array-interface object for a host buffer.  Keep that ordering
209    // in the shared core so Python versions without PEP 688's ``__buffer__``
210    // hook still report the public OverflowError for an oversized dimension
211    // instead of leaking the later buffer-protocol TypeError.
212    u32::try_from(width)
213        .map_err(|_| PilError::OverflowError("signed integer is greater than maximum".into()))?;
214    u32::try_from(height)
215        .map_err(|_| PilError::OverflowError("signed integer is greater than maximum".into()))?;
216    let mode_reinterprets_dtype = mode != entry.mode && !entry.color_modes.contains(&mode);
217    Ok(ArrayLayout {
218        mode: mode.to_string(),
219        raw_mode: explicit_mode.unwrap_or(entry.raw_mode).to_string(),
220        width,
221        height,
222        dimensions,
223        mode_reinterprets_dtype,
224    })
225}
226
227/// Build an image from a resolved array-interface layout and its packed bytes.
228///
229/// The caller resolves the descriptor before obtaining host buffer bytes so
230/// Pillow's validation-before-buffer ordering is preserved. Conversion and
231/// raw-image construction remain in the Rust core.
232pub fn from_resolved_array_interface(layout: &ArrayLayout, data: &[u8]) -> Result<Image, PilError> {
233    let width = u32::try_from(layout.width)
234        // Pillow's frombuffer dimension conversion raises this exact
235        // OverflowError before attempting allocation.
236        .map_err(|_| PilError::OverflowError("signed integer is greater than maximum".into()))?;
237    let height = u32::try_from(layout.height)
238        .map_err(|_| PilError::OverflowError("signed integer is greater than maximum".into()))?;
239
240    if layout.mode == "1" && layout.raw_mode == "1;8" {
241        // Pillow's ``|b1`` array typemap is a byte-per-pixel source decoder,
242        // not the packed bitmap layout accepted by Image.frombytes("1").
243        // Pack each nonzero source byte into the public mode-1 scanline before
244        // entering the ordinary core decoder.
245        let samples = layout
246            .width
247            .checked_mul(layout.height)
248            .ok_or_else(|| PilError::OverflowError("array dimensions overflow".into()))?;
249        let input = data
250            .get(..samples)
251            .ok_or_else(|| PilError::ValueError("not enough image data".into()))?;
252        let row_bytes = layout.width.div_ceil(8);
253        let output_len = row_bytes
254            .checked_mul(layout.height)
255            .ok_or_else(|| PilError::OverflowError("array buffer size overflow".into()))?;
256        let mut packed = vec![0u8; output_len];
257        for (index, &sample) in input.iter().enumerate() {
258            if sample != 0 {
259                let row = index / layout.width;
260                let column = index % layout.width;
261                packed[row * row_bytes + column / 8] |= 0x80 >> (column % 8);
262            }
263        }
264        return Image::frombytes("1", (width, height), &packed);
265    }
266
267    if let Some(normalized) = normalize_scalar_array(layout, data)? {
268        // Pillow's array typemap exposes several raw scalar encodings while
269        // the resulting public image remains mode I or F.  Normalize those
270        // encodings to the native four-byte representation before entering
271        // the ordinary Image::frombytes mode path.
272        return Image::frombytes(&layout.mode, (width, height), &normalized);
273    }
274    Image::frombytes(&layout.raw_mode, (width, height), data)
275}
276
277fn normalize_scalar_array(layout: &ArrayLayout, data: &[u8]) -> Result<Option<Vec<u8>>, PilError> {
278    let samples = layout
279        .width
280        .checked_mul(layout.height)
281        .ok_or_else(|| PilError::OverflowError("array dimensions overflow".into()))?;
282
283    let bytes_per_sample = match layout.raw_mode.as_str() {
284        "I;8" => Some(1),
285        "I;16S" | "I;16BS" => Some(2),
286        "I;32" | "I;32B" | "I;32BS" | "F;32BF" => Some(4),
287        "F;64F" | "F;64BF" => Some(8),
288        _ => None,
289    };
290    let Some(bytes_per_sample) = bytes_per_sample else {
291        return Ok(None);
292    };
293    let required = samples
294        .checked_mul(bytes_per_sample)
295        .ok_or_else(|| PilError::OverflowError("array buffer size overflow".into()))?;
296    let input = data
297        .get(..required)
298        .ok_or_else(|| PilError::ValueError("not enough image data".into()))?;
299    let output_capacity = samples
300        .checked_mul(4)
301        .ok_or_else(|| PilError::OverflowError("array buffer size overflow".into()))?;
302    let mut output = Vec::with_capacity(output_capacity);
303
304    if layout.mode == "I" {
305        for sample in input.chunks_exact(bytes_per_sample) {
306            let value = match layout.raw_mode.as_str() {
307                // Pillow's I;8 raw decoder widens the byte as unsigned even
308                // when the NumPy descriptor is signed |i1.
309                "I;8" => i32::from(sample[0]),
310                "I;16S" => i32::from(i16::from_le_bytes([sample[0], sample[1]])),
311                "I;16BS" => i32::from(i16::from_be_bytes([sample[0], sample[1]])),
312                "I;32" => u32::from_le_bytes(sample.try_into().unwrap()) as i32,
313                "I;32B" => u32::from_be_bytes(sample.try_into().unwrap()) as i32,
314                "I;32BS" => i32::from_be_bytes(sample.try_into().unwrap()),
315                _ => return Ok(None),
316            };
317            output.extend_from_slice(&value.to_ne_bytes());
318        }
319    } else if layout.mode == "F" {
320        for sample in input.chunks_exact(bytes_per_sample) {
321            // Pillow stores F images as float32, so f64 array inputs must
322            // intentionally narrow to the public image representation.
323            #[allow(clippy::cast_possible_truncation)]
324            let value = match layout.raw_mode.as_str() {
325                "F;32BF" => f32::from_be_bytes(sample.try_into().unwrap()),
326                "F;64F" => f64::from_le_bytes(sample.try_into().unwrap()) as f32,
327                "F;64BF" => f64::from_be_bytes(sample.try_into().unwrap()) as f32,
328                _ => return Ok(None),
329            };
330            output.extend_from_slice(&value.to_ne_bytes());
331        }
332    } else {
333        return Ok(None);
334    }
335
336    Ok(Some(output))
337}
338
339fn format_typekey_shape(shape_tail: &[usize]) -> String {
340    let mut values = vec![1, 1];
341    values.extend_from_slice(shape_tail);
342    format!(
343        "({})",
344        values
345            .iter()
346            .map(usize::to_string)
347            .collect::<Vec<_>>()
348            .join(", ")
349    )
350}