image/codecs/
png.rs

1//! Decoding and Encoding of PNG Images
2//!
3//! PNG (Portable Network Graphics) is an image format that supports lossless compression.
4//!
5//! # Related Links
6//! * <http://www.w3.org/TR/PNG/> - The PNG Specification
7
8use std::borrow::Cow;
9use std::io::{BufRead, Seek, Write};
10
11use png::{BlendOp, DeflateCompression, DisposeOp};
12
13use crate::animation::{Delay, Frame, Frames, Ratio};
14use crate::color::{Blend, ColorType, ExtendedColorType};
15use crate::error::{
16    DecodingError, ImageError, ImageResult, LimitError, LimitErrorKind, ParameterError,
17    ParameterErrorKind, UnsupportedError, UnsupportedErrorKind,
18};
19use crate::utils::vec_try_with_capacity;
20use crate::{
21    AnimationDecoder, DynamicImage, GenericImage, GenericImageView, ImageBuffer, ImageDecoder,
22    ImageEncoder, ImageFormat, Limits, Luma, LumaA, Rgb, Rgba, RgbaImage,
23};
24
25// http://www.w3.org/TR/PNG-Structure.html
26// The first eight bytes of a PNG file always contain the following (decimal) values:
27pub(crate) const PNG_SIGNATURE: [u8; 8] = [137, 80, 78, 71, 13, 10, 26, 10];
28const XMP_KEY: &str = "XML:com.adobe.xmp";
29const IPTC_KEYS: &[&str] = &["Raw profile type iptc", "Raw profile type 8bim"];
30
31/// PNG decoder
32pub struct PngDecoder<R: BufRead + Seek> {
33    color_type: ColorType,
34    reader: png::Reader<R>,
35    limits: Limits,
36}
37
38impl<R: BufRead + Seek> PngDecoder<R> {
39    /// Creates a new decoder that decodes from the stream ```r```
40    pub fn new(r: R) -> ImageResult<PngDecoder<R>> {
41        Self::with_limits(r, Limits::no_limits())
42    }
43
44    /// Creates a new decoder that decodes from the stream ```r``` with the given limits.
45    pub fn with_limits(r: R, limits: Limits) -> ImageResult<PngDecoder<R>> {
46        limits.check_support(&crate::LimitSupport::default())?;
47
48        let max_bytes = usize::try_from(limits.max_alloc.unwrap_or(u64::MAX)).unwrap_or(usize::MAX);
49        let mut decoder = png::Decoder::new_with_limits(r, png::Limits { bytes: max_bytes });
50        decoder.set_ignore_text_chunk(false);
51
52        let info = decoder.read_header_info().map_err(ImageError::from_png)?;
53        limits.check_dimensions(info.width, info.height)?;
54
55        // By default the PNG decoder will scale 16 bpc to 8 bpc, so custom
56        // transformations must be set. EXPAND preserves the default behavior
57        // expanding bpc < 8 to 8 bpc.
58        decoder.set_transformations(png::Transformations::EXPAND);
59        let reader = decoder.read_info().map_err(ImageError::from_png)?;
60        let (color_type, bits) = reader.output_color_type();
61        let color_type = match (color_type, bits) {
62            (png::ColorType::Grayscale, png::BitDepth::Eight) => ColorType::L8,
63            (png::ColorType::Grayscale, png::BitDepth::Sixteen) => ColorType::L16,
64            (png::ColorType::GrayscaleAlpha, png::BitDepth::Eight) => ColorType::La8,
65            (png::ColorType::GrayscaleAlpha, png::BitDepth::Sixteen) => ColorType::La16,
66            (png::ColorType::Rgb, png::BitDepth::Eight) => ColorType::Rgb8,
67            (png::ColorType::Rgb, png::BitDepth::Sixteen) => ColorType::Rgb16,
68            (png::ColorType::Rgba, png::BitDepth::Eight) => ColorType::Rgba8,
69            (png::ColorType::Rgba, png::BitDepth::Sixteen) => ColorType::Rgba16,
70
71            (png::ColorType::Grayscale, png::BitDepth::One) => {
72                return Err(unsupported_color(ExtendedColorType::L1))
73            }
74            (png::ColorType::GrayscaleAlpha, png::BitDepth::One) => {
75                return Err(unsupported_color(ExtendedColorType::La1))
76            }
77            (png::ColorType::Rgb, png::BitDepth::One) => {
78                return Err(unsupported_color(ExtendedColorType::Rgb1))
79            }
80            (png::ColorType::Rgba, png::BitDepth::One) => {
81                return Err(unsupported_color(ExtendedColorType::Rgba1))
82            }
83
84            (png::ColorType::Grayscale, png::BitDepth::Two) => {
85                return Err(unsupported_color(ExtendedColorType::L2))
86            }
87            (png::ColorType::GrayscaleAlpha, png::BitDepth::Two) => {
88                return Err(unsupported_color(ExtendedColorType::La2))
89            }
90            (png::ColorType::Rgb, png::BitDepth::Two) => {
91                return Err(unsupported_color(ExtendedColorType::Rgb2))
92            }
93            (png::ColorType::Rgba, png::BitDepth::Two) => {
94                return Err(unsupported_color(ExtendedColorType::Rgba2))
95            }
96
97            (png::ColorType::Grayscale, png::BitDepth::Four) => {
98                return Err(unsupported_color(ExtendedColorType::L4))
99            }
100            (png::ColorType::GrayscaleAlpha, png::BitDepth::Four) => {
101                return Err(unsupported_color(ExtendedColorType::La4))
102            }
103            (png::ColorType::Rgb, png::BitDepth::Four) => {
104                return Err(unsupported_color(ExtendedColorType::Rgb4))
105            }
106            (png::ColorType::Rgba, png::BitDepth::Four) => {
107                return Err(unsupported_color(ExtendedColorType::Rgba4))
108            }
109
110            (png::ColorType::Indexed, bits) => {
111                return Err(unsupported_color(ExtendedColorType::Unknown(bits as u8)))
112            }
113        };
114
115        Ok(PngDecoder {
116            color_type,
117            reader,
118            limits,
119        })
120    }
121
122    /// Returns the gamma value of the image or None if no gamma value is indicated.
123    ///
124    /// If an sRGB chunk is present this method returns a gamma value of 0.45455 and ignores the
125    /// value in the gAMA chunk. This is the recommended behavior according to the PNG standard:
126    ///
127    /// > When the sRGB chunk is present, [...] decoders that recognize the sRGB chunk but are not
128    /// > capable of colour management are recommended to ignore the gAMA and cHRM chunks, and use
129    /// > the values given above as if they had appeared in gAMA and cHRM chunks.
130    pub fn gamma_value(&self) -> ImageResult<Option<f64>> {
131        Ok(self
132            .reader
133            .info()
134            .source_gamma
135            .map(|x| f64::from(x.into_scaled()) / 100_000.0))
136    }
137
138    /// Turn this into an iterator over the animation frames.
139    ///
140    /// Reading the complete animation requires more memory than reading the data from the IDAT
141    /// frame–multiple frame buffers need to be reserved at the same time. We further do not
142    /// support compositing 16-bit colors. In any case this would be lossy as the interface of
143    /// animation decoders does not support 16-bit colors.
144    ///
145    /// If something is not supported or a limit is violated then the decoding step that requires
146    /// them will fail and an error will be returned instead of the frame. No further frames will
147    /// be returned.
148    pub fn apng(self) -> ImageResult<ApngDecoder<R>> {
149        Ok(ApngDecoder::new(self))
150    }
151
152    /// Returns if the image contains an animation.
153    ///
154    /// Note that the file itself decides if the default image is considered to be part of the
155    /// animation. When it is not the common interpretation is to use it as a thumbnail.
156    ///
157    /// If a non-animated image is converted into an `ApngDecoder` then its iterator is empty.
158    pub fn is_apng(&self) -> ImageResult<bool> {
159        Ok(self.reader.info().animation_control.is_some())
160    }
161}
162
163fn unsupported_color(ect: ExtendedColorType) -> ImageError {
164    ImageError::Unsupported(UnsupportedError::from_format_and_kind(
165        ImageFormat::Png.into(),
166        UnsupportedErrorKind::Color(ect),
167    ))
168}
169
170impl<R: BufRead + Seek> ImageDecoder for PngDecoder<R> {
171    fn dimensions(&self) -> (u32, u32) {
172        self.reader.info().size()
173    }
174
175    fn color_type(&self) -> ColorType {
176        self.color_type
177    }
178
179    fn icc_profile(&mut self) -> ImageResult<Option<Vec<u8>>> {
180        Ok(self.reader.info().icc_profile.as_ref().map(|x| x.to_vec()))
181    }
182
183    fn exif_metadata(&mut self) -> ImageResult<Option<Vec<u8>>> {
184        Ok(self
185            .reader
186            .info()
187            .exif_metadata
188            .as_ref()
189            .map(|x| x.to_vec()))
190    }
191
192    fn xmp_metadata(&mut self) -> ImageResult<Option<Vec<u8>>> {
193        if let Some(mut itx_chunk) = self
194            .reader
195            .info()
196            .utf8_text
197            .iter()
198            .find(|chunk| chunk.keyword.contains(XMP_KEY))
199            .cloned()
200        {
201            itx_chunk.decompress_text().map_err(ImageError::from_png)?;
202            return itx_chunk
203                .get_text()
204                .map(|text| Some(text.as_bytes().to_vec()))
205                .map_err(ImageError::from_png);
206        }
207        Ok(None)
208    }
209
210    fn iptc_metadata(&mut self) -> ImageResult<Option<Vec<u8>>> {
211        if let Some(mut text_chunk) = self
212            .reader
213            .info()
214            .compressed_latin1_text
215            .iter()
216            .find(|chunk| IPTC_KEYS.iter().any(|key| chunk.keyword.contains(key)))
217            .cloned()
218        {
219            text_chunk.decompress_text().map_err(ImageError::from_png)?;
220            return text_chunk
221                .get_text()
222                .map(|text| Some(text.as_bytes().to_vec()))
223                .map_err(ImageError::from_png);
224        }
225
226        if let Some(text_chunk) = self
227            .reader
228            .info()
229            .uncompressed_latin1_text
230            .iter()
231            .find(|chunk| IPTC_KEYS.iter().any(|key| chunk.keyword.contains(key)))
232            .cloned()
233        {
234            return Ok(Some(text_chunk.text.into_bytes()));
235        }
236        Ok(None)
237    }
238
239    fn read_image(mut self, buf: &mut [u8]) -> ImageResult<()> {
240        use byteorder_lite::{BigEndian, ByteOrder, NativeEndian};
241
242        assert_eq!(u64::try_from(buf.len()), Ok(self.total_bytes()));
243        self.reader.next_frame(buf).map_err(ImageError::from_png)?;
244        // PNG images are big endian. For 16 bit per channel and larger types,
245        // the buffer may need to be reordered to native endianness per the
246        // contract of `read_image`.
247        // TODO: assumes equal channel bit depth.
248        let bpc = self.color_type().bytes_per_pixel() / self.color_type().channel_count();
249
250        match bpc {
251            1 => (), // No reodering necessary for u8
252            2 => buf.chunks_exact_mut(2).for_each(|c| {
253                let v = BigEndian::read_u16(c);
254                NativeEndian::write_u16(c, v);
255            }),
256            _ => unreachable!(),
257        }
258        Ok(())
259    }
260
261    fn read_image_boxed(self: Box<Self>, buf: &mut [u8]) -> ImageResult<()> {
262        (*self).read_image(buf)
263    }
264
265    fn set_limits(&mut self, limits: Limits) -> ImageResult<()> {
266        limits.check_support(&crate::LimitSupport::default())?;
267        let info = self.reader.info();
268        limits.check_dimensions(info.width, info.height)?;
269        self.limits = limits;
270        // TODO: add `png::Reader::change_limits()` and call it here
271        // to also constrain the internal buffer allocations in the PNG crate
272        Ok(())
273    }
274}
275
276/// An [`AnimationDecoder`] adapter of [`PngDecoder`].
277///
278/// See [`PngDecoder::apng`] for more information.
279///
280/// [`AnimationDecoder`]: ../trait.AnimationDecoder.html
281/// [`PngDecoder`]: struct.PngDecoder.html
282/// [`PngDecoder::apng`]: struct.PngDecoder.html#method.apng
283pub struct ApngDecoder<R: BufRead + Seek> {
284    inner: PngDecoder<R>,
285    /// The current output buffer.
286    current: Option<RgbaImage>,
287    /// The previous output buffer, used for dispose op previous.
288    previous: Option<RgbaImage>,
289    /// The dispose op of the current frame.
290    dispose: DisposeOp,
291
292    /// The region to dispose of the previous frame.
293    dispose_region: Option<(u32, u32, u32, u32)>,
294    /// The number of image still expected to be able to load.
295    remaining: u32,
296    /// The next (first) image is the thumbnail.
297    has_thumbnail: bool,
298}
299
300impl<R: BufRead + Seek> ApngDecoder<R> {
301    fn new(inner: PngDecoder<R>) -> Self {
302        let info = inner.reader.info();
303        let remaining = match info.animation_control() {
304            // The expected number of fcTL in the remaining image.
305            Some(actl) => actl.num_frames,
306            None => 0,
307        };
308        // If the IDAT has no fcTL then it is not part of the animation counted by
309        // num_frames. All following fdAT chunks must be preceded by an fcTL
310        let has_thumbnail = info.frame_control.is_none();
311        ApngDecoder {
312            inner,
313            current: None,
314            previous: None,
315            dispose: DisposeOp::Background,
316            dispose_region: None,
317            remaining,
318            has_thumbnail,
319        }
320    }
321
322    // TODO: thumbnail(&mut self) -> Option<impl ImageDecoder<'_>>
323
324    /// Decode one subframe and overlay it on the canvas.
325    fn mix_next_frame(&mut self) -> Result<Option<&RgbaImage>, ImageError> {
326        // The iterator always produces RGBA8 images
327        const COLOR_TYPE: ColorType = ColorType::Rgba8;
328
329        // Allocate the buffers, honoring the memory limits
330        let (width, height) = self.inner.dimensions();
331        {
332            let limits = &mut self.inner.limits;
333            if self.previous.is_none() {
334                limits.reserve_buffer(width, height, COLOR_TYPE)?;
335                self.previous = Some(RgbaImage::new(width, height));
336            }
337
338            if self.current.is_none() {
339                limits.reserve_buffer(width, height, COLOR_TYPE)?;
340                self.current = Some(RgbaImage::new(width, height));
341            }
342        }
343
344        // Remove this image from remaining.
345        self.remaining = match self.remaining.checked_sub(1) {
346            None => return Ok(None),
347            Some(next) => next,
348        };
349
350        // Shorten ourselves to 0 in case of error.
351        let remaining = self.remaining;
352        self.remaining = 0;
353
354        // Skip the thumbnail that is not part of the animation.
355        if self.has_thumbnail {
356            // Clone the limits so that our one-off allocation that's destroyed after this scope doesn't persist
357            let mut limits = self.inner.limits.clone();
358
359            let buffer_size = self.inner.reader.output_buffer_size().ok_or_else(|| {
360                ImageError::Limits(LimitError::from_kind(LimitErrorKind::InsufficientMemory))
361            })?;
362
363            limits.reserve_usize(buffer_size)?;
364            let mut buffer = vec![0; buffer_size];
365            // TODO: add `png::Reader::change_limits()` and call it here
366            // to also constrain the internal buffer allocations in the PNG crate
367            self.inner
368                .reader
369                .next_frame(&mut buffer)
370                .map_err(ImageError::from_png)?;
371            self.has_thumbnail = false;
372        }
373
374        self.animatable_color_type()?;
375
376        // We've initialized them earlier in this function
377        let previous = self.previous.as_mut().unwrap();
378        let current = self.current.as_mut().unwrap();
379
380        // Dispose of the previous frame.
381
382        match self.dispose {
383            DisposeOp::None => {
384                previous.clone_from(current);
385            }
386            DisposeOp::Background => {
387                previous.clone_from(current);
388                if let Some((px, py, width, height)) = self.dispose_region {
389                    let mut region_current = current.sub_image(px, py, width, height);
390
391                    // FIXME: This is a workaround for the fact that `pixels_mut` is not implemented
392                    let pixels: Vec<_> = region_current.pixels().collect();
393
394                    for (x, y, _) in &pixels {
395                        region_current.put_pixel(*x, *y, Rgba::from([0, 0, 0, 0]));
396                    }
397                } else {
398                    // The first frame is always a background frame.
399                    current.pixels_mut().for_each(|pixel| {
400                        *pixel = Rgba::from([0, 0, 0, 0]);
401                    });
402                }
403            }
404            DisposeOp::Previous => {
405                let (px, py, width, height) = self
406                    .dispose_region
407                    .expect("The first frame must not set dispose=Previous");
408                let region_previous = previous.sub_image(px, py, width, height);
409                current
410                    .copy_from(&region_previous.to_image(), px, py)
411                    .unwrap();
412            }
413        }
414
415        // The allocations from now on are not going to persist,
416        // and will be destroyed at the end of the scope.
417        // Clone the limits so that any changes to them die with the allocations.
418        let mut limits = self.inner.limits.clone();
419
420        // Read next frame data.
421        let raw_frame_size = self.inner.reader.output_buffer_size().ok_or_else(|| {
422            ImageError::Limits(LimitError::from_kind(LimitErrorKind::InsufficientMemory))
423        })?;
424
425        limits.reserve_usize(raw_frame_size)?;
426        let mut buffer = vec![0; raw_frame_size];
427        // TODO: add `png::Reader::change_limits()` and call it here
428        // to also constrain the internal buffer allocations in the PNG crate
429        self.inner
430            .reader
431            .next_frame(&mut buffer)
432            .map_err(ImageError::from_png)?;
433        let info = self.inner.reader.info();
434
435        // Find out how to interpret the decoded frame.
436        let (width, height, px, py, blend);
437        match info.frame_control() {
438            None => {
439                width = info.width;
440                height = info.height;
441                px = 0;
442                py = 0;
443                blend = BlendOp::Source;
444            }
445            Some(fc) => {
446                width = fc.width;
447                height = fc.height;
448                px = fc.x_offset;
449                py = fc.y_offset;
450                blend = fc.blend_op;
451                self.dispose = fc.dispose_op;
452            }
453        }
454
455        self.dispose_region = Some((px, py, width, height));
456
457        // Turn the data into an rgba image proper.
458        limits.reserve_buffer(width, height, COLOR_TYPE)?;
459        let source = match self.inner.color_type {
460            ColorType::L8 => {
461                let image = ImageBuffer::<Luma<_>, _>::from_raw(width, height, buffer).unwrap();
462                DynamicImage::ImageLuma8(image).into_rgba8()
463            }
464            ColorType::La8 => {
465                let image = ImageBuffer::<LumaA<_>, _>::from_raw(width, height, buffer).unwrap();
466                DynamicImage::ImageLumaA8(image).into_rgba8()
467            }
468            ColorType::Rgb8 => {
469                let image = ImageBuffer::<Rgb<_>, _>::from_raw(width, height, buffer).unwrap();
470                DynamicImage::ImageRgb8(image).into_rgba8()
471            }
472            ColorType::Rgba8 => ImageBuffer::<Rgba<_>, _>::from_raw(width, height, buffer).unwrap(),
473            ColorType::L16 | ColorType::Rgb16 | ColorType::La16 | ColorType::Rgba16 => {
474                // TODO: to enable remove restriction in `animatable_color_type` method.
475                unreachable!("16-bit apng not yet support")
476            }
477            _ => unreachable!("Invalid png color"),
478        };
479        // We've converted the raw frame to RGBA8 and disposed of the original allocation
480        limits.free_usize(raw_frame_size);
481
482        match blend {
483            BlendOp::Source => {
484                current
485                    .copy_from(&source, px, py)
486                    .expect("Invalid png image not detected in png");
487            }
488            BlendOp::Over => {
489                // TODO: investigate speed, speed-ups, and bounds-checks.
490                for (x, y, p) in source.enumerate_pixels() {
491                    current.get_pixel_mut(x + px, y + py).blend(p);
492                }
493            }
494        }
495
496        // Ok, we can proceed with actually remaining images.
497        self.remaining = remaining;
498        // Return composited output buffer.
499
500        Ok(Some(self.current.as_ref().unwrap()))
501    }
502
503    fn animatable_color_type(&self) -> Result<(), ImageError> {
504        match self.inner.color_type {
505            ColorType::L8 | ColorType::Rgb8 | ColorType::La8 | ColorType::Rgba8 => Ok(()),
506            // TODO: do not handle multi-byte colors. Remember to implement it in `mix_next_frame`.
507            ColorType::L16 | ColorType::Rgb16 | ColorType::La16 | ColorType::Rgba16 => {
508                Err(unsupported_color(self.inner.color_type.into()))
509            }
510            _ => unreachable!("{:?} not a valid png color", self.inner.color_type),
511        }
512    }
513}
514
515impl<'a, R: BufRead + Seek + 'a> AnimationDecoder<'a> for ApngDecoder<R> {
516    fn into_frames(self) -> Frames<'a> {
517        struct FrameIterator<R: BufRead + Seek>(ApngDecoder<R>);
518
519        impl<R: BufRead + Seek> Iterator for FrameIterator<R> {
520            type Item = ImageResult<Frame>;
521
522            fn next(&mut self) -> Option<Self::Item> {
523                let image = match self.0.mix_next_frame() {
524                    Ok(Some(image)) => image.clone(),
525                    Ok(None) => return None,
526                    Err(err) => return Some(Err(err)),
527                };
528
529                let info = self.0.inner.reader.info();
530                let fc = info.frame_control().unwrap();
531                // PNG delays are rations in seconds.
532                let num = u32::from(fc.delay_num) * 1_000u32;
533                let denom = match fc.delay_den {
534                    // The standard dictates to replace by 100 when the denominator is 0.
535                    0 => 100,
536                    d => u32::from(d),
537                };
538                let delay = Delay::from_ratio(Ratio::new(num, denom));
539                Some(Ok(Frame::from_parts(image, 0, 0, delay)))
540            }
541        }
542
543        Frames::new(Box::new(FrameIterator(self)))
544    }
545}
546
547/// PNG encoder
548pub struct PngEncoder<W: Write> {
549    w: W,
550    compression: CompressionType,
551    filter: FilterType,
552    icc_profile: Vec<u8>,
553    exif_metadata: Vec<u8>,
554}
555
556/// DEFLATE compression level of a PNG encoder. The default setting is `Fast`.
557#[derive(Clone, Copy, Debug, Eq, PartialEq)]
558#[non_exhaustive]
559#[derive(Default)]
560pub enum CompressionType {
561    /// Default compression level
562    Default,
563    /// Fast, minimal compression
564    #[default]
565    Fast,
566    /// High compression level
567    Best,
568    /// No compression whatsoever
569    Uncompressed,
570    /// Detailed compression level between 1 and 9
571    Level(u8),
572}
573
574/// Filter algorithms used to process image data to improve compression.
575///
576/// The default filter is `Adaptive`.
577#[derive(Clone, Copy, Debug, Eq, PartialEq)]
578#[non_exhaustive]
579#[derive(Default)]
580pub enum FilterType {
581    /// No processing done, best used for low bit depth grayscale or data with a
582    /// low color count
583    NoFilter,
584    /// Filters based on previous pixel in the same scanline
585    Sub,
586    /// Filters based on the scanline above
587    Up,
588    /// Filters based on the average of left and right neighbor pixels
589    Avg,
590    /// Algorithm that takes into account the left, upper left, and above pixels
591    Paeth,
592    /// Uses a heuristic to select one of the preceding filters for each
593    /// scanline rather than one filter for the entire image
594    #[default]
595    Adaptive,
596}
597
598impl<W: Write> PngEncoder<W> {
599    /// Create a new encoder that writes its output to ```w```
600    pub fn new(w: W) -> PngEncoder<W> {
601        PngEncoder {
602            w,
603            compression: CompressionType::default(),
604            filter: FilterType::default(),
605            icc_profile: Vec::new(),
606            exif_metadata: Vec::new(),
607        }
608    }
609
610    /// Create a new encoder that writes its output to `w` with `CompressionType` `compression` and
611    /// `FilterType` `filter`.
612    ///
613    /// It is best to view the options as a _hint_ to the implementation on the smallest or fastest
614    /// option for encoding a particular image. That is, using options that map directly to a PNG
615    /// image parameter will use this parameter where possible. But variants that have no direct
616    /// mapping may be interpreted differently in minor versions. The exact output is expressly
617    /// __not__ part of the SemVer stability guarantee.
618    ///
619    /// Note that it is not optimal to use a single filter type, so an adaptive
620    /// filter type is selected as the default. The filter which best minimizes
621    /// file size may change with the type of compression used.
622    pub fn new_with_quality(
623        w: W,
624        compression: CompressionType,
625        filter: FilterType,
626    ) -> PngEncoder<W> {
627        PngEncoder {
628            w,
629            compression,
630            filter,
631            icc_profile: Vec::new(),
632            exif_metadata: Vec::new(),
633        }
634    }
635
636    fn encode_inner(
637        self,
638        data: &[u8],
639        width: u32,
640        height: u32,
641        color: ExtendedColorType,
642    ) -> ImageResult<()> {
643        let (ct, bits) = match color {
644            ExtendedColorType::L8 => (png::ColorType::Grayscale, png::BitDepth::Eight),
645            ExtendedColorType::L16 => (png::ColorType::Grayscale, png::BitDepth::Sixteen),
646            ExtendedColorType::La8 => (png::ColorType::GrayscaleAlpha, png::BitDepth::Eight),
647            ExtendedColorType::La16 => (png::ColorType::GrayscaleAlpha, png::BitDepth::Sixteen),
648            ExtendedColorType::Rgb8 => (png::ColorType::Rgb, png::BitDepth::Eight),
649            ExtendedColorType::Rgb16 => (png::ColorType::Rgb, png::BitDepth::Sixteen),
650            ExtendedColorType::Rgba8 => (png::ColorType::Rgba, png::BitDepth::Eight),
651            ExtendedColorType::Rgba16 => (png::ColorType::Rgba, png::BitDepth::Sixteen),
652            _ => {
653                return Err(ImageError::Unsupported(
654                    UnsupportedError::from_format_and_kind(
655                        ImageFormat::Png.into(),
656                        UnsupportedErrorKind::Color(color),
657                    ),
658                ))
659            }
660        };
661
662        let comp = match self.compression {
663            CompressionType::Default => png::Compression::Balanced,
664            CompressionType::Best => png::Compression::High,
665            CompressionType::Fast => png::Compression::Fast,
666            CompressionType::Uncompressed => png::Compression::NoCompression,
667            CompressionType::Level(0) => png::Compression::NoCompression,
668            CompressionType::Level(_) => png::Compression::Fast, // whatever, will be overridden
669        };
670
671        let advanced_comp = match self.compression {
672            // Do not set level 0 as a Zlib level to avoid Zlib backend variance.
673            // For example, in miniz_oxide level 0 is very slow.
674            CompressionType::Level(n @ 1..) => Some(DeflateCompression::Level(n)),
675            _ => None,
676        };
677
678        let filter = match self.filter {
679            FilterType::NoFilter => png::Filter::NoFilter,
680            FilterType::Sub => png::Filter::Sub,
681            FilterType::Up => png::Filter::Up,
682            FilterType::Avg => png::Filter::Avg,
683            FilterType::Paeth => png::Filter::Paeth,
684            FilterType::Adaptive => png::Filter::Adaptive,
685        };
686
687        let mut info = png::Info::with_size(width, height);
688
689        if !self.icc_profile.is_empty() {
690            info.icc_profile = Some(Cow::Borrowed(&self.icc_profile));
691        }
692        if !self.exif_metadata.is_empty() {
693            info.exif_metadata = Some(Cow::Borrowed(&self.exif_metadata));
694        }
695
696        let mut encoder =
697            png::Encoder::with_info(self.w, info).map_err(|e| ImageError::IoError(e.into()))?;
698
699        encoder.set_color(ct);
700        encoder.set_depth(bits);
701        encoder.set_compression(comp);
702        if let Some(compression) = advanced_comp {
703            encoder.set_deflate_compression(compression);
704        }
705        encoder.set_filter(filter);
706        let mut writer = encoder
707            .write_header()
708            .map_err(|e| ImageError::IoError(e.into()))?;
709        writer
710            .write_image_data(data)
711            .map_err(|e| ImageError::IoError(e.into()))
712    }
713}
714
715impl<W: Write> ImageEncoder for PngEncoder<W> {
716    /// Write a PNG image with the specified width, height, and color type.
717    ///
718    /// For color types with 16-bit per channel or larger, the contents of `buf` should be in
719    /// native endian. `PngEncoder` will automatically convert to big endian as required by the
720    /// underlying PNG format.
721    #[track_caller]
722    fn write_image(
723        self,
724        buf: &[u8],
725        width: u32,
726        height: u32,
727        color_type: ExtendedColorType,
728    ) -> ImageResult<()> {
729        use ExtendedColorType::*;
730
731        let expected_buffer_len = color_type.buffer_size(width, height);
732        assert_eq!(
733            expected_buffer_len,
734            buf.len() as u64,
735            "Invalid buffer length: expected {expected_buffer_len} got {} for {width}x{height} image",
736            buf.len(),
737        );
738
739        // PNG images are big endian. For 16 bit per channel and larger types,
740        // the buffer may need to be reordered to big endian per the
741        // contract of `write_image`.
742        // TODO: assumes equal channel bit depth.
743        match color_type {
744            L8 | La8 | Rgb8 | Rgba8 => {
745                // No reodering necessary for u8
746                self.encode_inner(buf, width, height, color_type)
747            }
748            L16 | La16 | Rgb16 | Rgba16 => {
749                // Because the buffer is immutable and the PNG encoder does not
750                // yet take Write/Read traits, create a temporary buffer for
751                // big endian reordering.
752                let mut reordered;
753                let buf = if cfg!(target_endian = "little") {
754                    reordered = vec_try_with_capacity(buf.len())?;
755                    reordered.extend(buf.chunks_exact(2).flat_map(|le| [le[1], le[0]]));
756                    &reordered
757                } else {
758                    buf
759                };
760                self.encode_inner(buf, width, height, color_type)
761            }
762            _ => Err(ImageError::Unsupported(
763                UnsupportedError::from_format_and_kind(
764                    ImageFormat::Png.into(),
765                    UnsupportedErrorKind::Color(color_type),
766                ),
767            )),
768        }
769    }
770
771    fn set_icc_profile(&mut self, icc_profile: Vec<u8>) -> Result<(), UnsupportedError> {
772        self.icc_profile = icc_profile;
773        Ok(())
774    }
775
776    fn set_exif_metadata(&mut self, exif: Vec<u8>) -> Result<(), UnsupportedError> {
777        self.exif_metadata = exif;
778        Ok(())
779    }
780}
781
782impl ImageError {
783    fn from_png(err: png::DecodingError) -> ImageError {
784        use png::DecodingError::*;
785        match err {
786            IoError(err) => ImageError::IoError(err),
787            // The input image was not a valid PNG.
788            err @ Format(_) => {
789                ImageError::Decoding(DecodingError::new(ImageFormat::Png.into(), err))
790            }
791            // Other is used when:
792            // - The decoder is polled for more animation frames despite being done (or not being animated
793            //   in the first place).
794            // - The output buffer does not have the required size.
795            err @ Parameter(_) => ImageError::Parameter(ParameterError::from_kind(
796                ParameterErrorKind::Generic(err.to_string()),
797            )),
798            LimitsExceeded => {
799                ImageError::Limits(LimitError::from_kind(LimitErrorKind::InsufficientMemory))
800            }
801        }
802    }
803}
804
805#[cfg(test)]
806mod tests {
807    use super::*;
808    use crate::io::free_functions::decoder_to_vec;
809    use std::io::{BufReader, Cursor, Read};
810
811    #[test]
812    fn ensure_no_decoder_off_by_one() {
813        let dec = PngDecoder::new(BufReader::new(
814            std::fs::File::open("tests/images/png/bugfixes/debug_triangle_corners_widescreen.png")
815                .unwrap(),
816        ))
817        .expect("Unable to read PNG file (does it exist?)");
818
819        assert_eq![(2000, 1000), dec.dimensions()];
820
821        assert_eq![
822            ColorType::Rgb8,
823            dec.color_type(),
824            "Image MUST have the Rgb8 format"
825        ];
826
827        let correct_bytes = decoder_to_vec(dec)
828            .expect("Unable to read file")
829            .bytes()
830            .map(|x| x.expect("Unable to read byte"))
831            .collect::<Vec<u8>>();
832
833        assert_eq![6_000_000, correct_bytes.len()];
834    }
835
836    #[test]
837    fn underlying_error() {
838        use std::error::Error;
839
840        let mut not_png =
841            std::fs::read("tests/images/png/bugfixes/debug_triangle_corners_widescreen.png")
842                .unwrap();
843        not_png[0] = 0;
844
845        let error = PngDecoder::new(Cursor::new(&not_png)).err().unwrap();
846        let _ = error
847            .source()
848            .unwrap()
849            .downcast_ref::<png::DecodingError>()
850            .expect("Caused by a png error");
851    }
852
853    #[test]
854    fn encode_bad_color_type() {
855        // regression test for issue #1663
856        let image = DynamicImage::new_rgb32f(1, 1);
857        let mut target = Cursor::new(vec![]);
858        let _ = image.write_to(&mut target, ImageFormat::Png);
859    }
860}
image/codecs/png.rs

image/codecs/
png.rs
