Split PNM ImageFormat into subformats for PBM, PGM, etc.

src/codecs/pnm/mod.rs

@@ -1,9 +1,18 @@
-//! Decoding of netpbm image formats (pbm, pgm, ppm and pam).
+//! Decoding and Encoding of netpbm image formats (PBM, PGM, PPM, PNM, PAM).
 //!
-//! The formats pbm, pgm and ppm are fully supported. Only the official subformats
-//! (`BLACKANDWHITE`, `GRAYSCALE`, `RGB`, `BLACKANDWHITE_ALPHA`, `GRAYSCALE_ALPHA`,
-//! and `RGB_ALPHA`) of pam are supported; custom tuple types have no clear
-//! interpretation as an image and will be rejected.
+//! The PnmDecoder supports all PBM, PGM, and PPM subformats. (PNM images may contain
+//! any of PBM, PGM, or PPM content.) Only the official subformats (`BLACKANDWHITE`,
+//! `GRAYSCALE`, `RGB`, `BLACKANDWHITE_ALPHA`, `GRAYSCALE_ALPHA`, and `RGB_ALPHA`)
+//! of PAM are decodable; custom tuple types have no clear interpretation as an
+//! image and will be rejected.
+//!
+//!  # Related Links
+//!  * <https://netpbm.sourceforge.net/doc/pbm.html> - specification for PBM
+//!  * <https://netpbm.sourceforge.net/doc/pgm.html> - specification for PGM
+//!  * <https://netpbm.sourceforge.net/doc/ppm.html> - specification for PPM
+//!  * <https://netpbm.sourceforge.net/doc/pnm.html> - definition for PNM
+//!  * <https://netpbm.sourceforge.net/doc/pam.html> - specification for PAM
+
 use self::autobreak::AutoBreak;
 pub use self::decoder::PnmDecoder;
 pub use self::encoder::PnmEncoder;

src/io/format.rs

@@ -21,9 +21,21 @@ pub enum ImageFormat {
     /// An Image in WEBP Format
     WebP,
 
+    /// An Image in PBM Format
+    Pbm,
+
+    /// An Image in PGM Format
+    Pgm,
+
+    /// An Image in PPM Format
+    Ppm,
+
     /// An Image in general PNM Format
     Pnm,
 
+    /// An Image in PAM Format
+    Pam,
+
     /// An Image in TIFF Format
     Tiff,
 
@@ -84,7 +96,11 @@ impl ImageFormat {
                 "ico" => ImageFormat::Ico,
                 "hdr" => ImageFormat::Hdr,
                 "exr" => ImageFormat::OpenExr,
-                "pbm" | "pam" | "ppm" | "pgm" | "pnm" => ImageFormat::Pnm,
+                "pbm" => ImageFormat::Pbm,
+                "pgm" => ImageFormat::Pgm,
+                "ppm" => ImageFormat::Ppm,
+                "pnm" => ImageFormat::Pnm,
+                "pam" => ImageFormat::Pam,
                 "ff" => ImageFormat::Farbfeld,
                 "qoi" => ImageFormat::Qoi,
                 _ => return None,
@@ -154,10 +170,11 @@ impl ImageFormat {
             "image/x-icon" | "image/vnd.microsoft.icon" => Some(ImageFormat::Ico),
             "image/vnd.radiance" => Some(ImageFormat::Hdr),
             "image/x-exr" => Some(ImageFormat::OpenExr),
-            "image/x-portable-bitmap"
-            | "image/x-portable-graymap"
-            | "image/x-portable-pixmap"
-            | "image/x-portable-anymap" => Some(ImageFormat::Pnm),
+            "image/x-portable-bitmap" => Some(ImageFormat::Pbm),
+            "image/x-portable-graymap" => Some(ImageFormat::Pgm),
+            "image/x-portable-pixmap" => Some(ImageFormat::Ppm),
+            "image/x-portable-anymap" => Some(ImageFormat::Ppm),
+            "image/x-portable-arbitrarymap" => Some(ImageFormat::Pam),
             // Qoi's MIME type is being worked on.
             // See: https://github.com/phoboslab/qoi/issues/167
             "image/x-qoi" => Some(ImageFormat::Qoi),
@@ -200,8 +217,11 @@ impl ImageFormat {
             ImageFormat::Ico => "image/x-icon",
             ImageFormat::Hdr => "image/vnd.radiance",
             ImageFormat::OpenExr => "image/x-exr",
-            // return the most general MIME type
+            ImageFormat::Pbm => "image/x-portable-bitmap",
+            ImageFormat::Pgm => "image/x-portable-graymap",
+            ImageFormat::Ppm => "image/x-portable-pixmap",
             ImageFormat::Pnm => "image/x-portable-anymap",
+            ImageFormat::Pam => "image/x-portable-arbitrarymap",
             // Qoi's MIME type is being worked on.
             // See: https://github.com/phoboslab/qoi/issues/167
             ImageFormat::Qoi => "image/x-qoi",
@@ -226,7 +246,11 @@ impl ImageFormat {
             ImageFormat::Ico => true,
             ImageFormat::Hdr => true,
             ImageFormat::OpenExr => true,
+            ImageFormat::Pbm => true,
+            ImageFormat::Pgm => true,
+            ImageFormat::Ppm => true,
             ImageFormat::Pnm => true,
+            ImageFormat::Pam => true,
             ImageFormat::Farbfeld => true,
             ImageFormat::Avif => true,
             ImageFormat::Qoi => true,
@@ -246,7 +270,11 @@ impl ImageFormat {
             ImageFormat::Bmp => true,
             ImageFormat::Tiff => true,
             ImageFormat::Tga => true,
+            ImageFormat::Pbm => true,
+            ImageFormat::Pgm => true,
+            ImageFormat::Ppm => true,
             ImageFormat::Pnm => true,
+            ImageFormat::Pam => true,
             ImageFormat::Farbfeld => true,
             ImageFormat::Avif => true,
             ImageFormat::WebP => true,
@@ -273,7 +301,11 @@ impl ImageFormat {
             ImageFormat::Jpeg => &["jpg", "jpeg"],
             ImageFormat::Gif => &["gif"],
             ImageFormat::WebP => &["webp"],
-            ImageFormat::Pnm => &["pbm", "pam", "ppm", "pgm", "pnm"],
+            ImageFormat::Pbm => &["pbm"],
+            ImageFormat::Pgm => &["pgm"],
+            ImageFormat::Ppm => &["ppm"],
+            ImageFormat::Pnm => &["pnm"],
+            ImageFormat::Pam => &["pam"],
             ImageFormat::Tiff => &["tiff", "tif"],
             ImageFormat::Tga => &["tga"],
             ImageFormat::Bmp => &["bmp"],
@@ -305,7 +337,11 @@ impl ImageFormat {
             ImageFormat::Ico => cfg!(feature = "ico"),
             ImageFormat::Hdr => cfg!(feature = "hdr"),
             ImageFormat::OpenExr => cfg!(feature = "exr"),
-            ImageFormat::Pnm => cfg!(feature = "pnm"),
+            ImageFormat::Pbm
+            | ImageFormat::Pgm
+            | ImageFormat::Ppm
+            | ImageFormat::Pnm
+            | ImageFormat::Pam => cfg!(feature = "pnm"),
             ImageFormat::Farbfeld => cfg!(feature = "ff"),
             ImageFormat::Avif => cfg!(feature = "avif-native"),
             ImageFormat::Qoi => cfg!(feature = "qoi"),
@@ -327,7 +363,11 @@ impl ImageFormat {
             ImageFormat::Bmp => cfg!(feature = "bmp"),
             ImageFormat::Tiff => cfg!(feature = "tiff"),
             ImageFormat::Tga => cfg!(feature = "tga"),
-            ImageFormat::Pnm => cfg!(feature = "pnm"),
+            ImageFormat::Pbm
+            | ImageFormat::Pgm
+            | ImageFormat::Ppm
+            | ImageFormat::Pnm
+            | ImageFormat::Pam => cfg!(feature = "pnm"),
             ImageFormat::Farbfeld => cfg!(feature = "ff"),
             ImageFormat::Avif => cfg!(feature = "avif"),
             ImageFormat::WebP => cfg!(feature = "webp"),
@@ -347,7 +387,11 @@ impl ImageFormat {
             ImageFormat::Bmp,
             ImageFormat::Tiff,
             ImageFormat::Tga,
+            ImageFormat::Pbm,
+            ImageFormat::Pgm,
+            ImageFormat::Ppm,
             ImageFormat::Pnm,
+            ImageFormat::Pam,
             ImageFormat::Farbfeld,
             ImageFormat::Avif,
             ImageFormat::WebP,
@@ -385,22 +429,19 @@ mod tests {
         assert_eq!(from_path("./a.Ico").unwrap(), ImageFormat::Ico);
         assert_eq!(from_path("./a.hdr").unwrap(), ImageFormat::Hdr);
         assert_eq!(from_path("./a.exr").unwrap(), ImageFormat::OpenExr);
-        assert_eq!(from_path("./a.pbm").unwrap(), ImageFormat::Pnm);
-        assert_eq!(from_path("./a.pAM").unwrap(), ImageFormat::Pnm);
-        assert_eq!(from_path("./a.Ppm").unwrap(), ImageFormat::Pnm);
-        assert_eq!(from_path("./a.pgm").unwrap(), ImageFormat::Pnm);
+        assert_eq!(from_path("./a.pbm").unwrap(), ImageFormat::Pbm);
+        assert_eq!(from_path("./a.pgm").unwrap(), ImageFormat::Pgm);
+        assert_eq!(from_path("./a.Ppm").unwrap(), ImageFormat::Ppm);
+        assert_eq!(from_path("./a.pnm").unwrap(), ImageFormat::Pnm);
+        assert_eq!(from_path("./a.PAM").unwrap(), ImageFormat::Pam);
         assert_eq!(from_path("./a.AViF").unwrap(), ImageFormat::Avif);
         assert!(from_path("./a.txt").is_err());
         assert!(from_path("./a").is_err());
     }
 
     #[test]
     fn image_formats_are_recognized() {
-        use ImageFormat::*;
-        const ALL_FORMATS: &[ImageFormat] = &[
-            Avif, Png, Jpeg, Gif, WebP, Pnm, Tiff, Tga, Bmp, Ico, Hdr, Farbfeld, OpenExr,
-        ];
-        for &format in ALL_FORMATS {
+        for format in ImageFormat::all() {
             let mut file = Path::new("file.nothing").to_owned();
             for ext in format.extensions_str() {
                 assert!(file.set_extension(ext));

src/io/free_functions.rs

@@ -67,7 +67,28 @@ pub(crate) fn encoder_for_format<'a, W: Write + Seek>(
         #[cfg(feature = "jpeg")]
         ImageFormat::Jpeg => Box::new(jpeg::JpegEncoder::new(buffered_write)),
         #[cfg(feature = "pnm")]
-        ImageFormat::Pnm => Box::new(pnm::PnmEncoder::new(buffered_write)),
+        ImageFormat::Pbm => Box::new(
+            pnm::PnmEncoder::new(buffered_write)
+                .with_subtype(pnm::PnmSubtype::Bitmap(pnm::SampleEncoding::Binary)),
+        ),
+        #[cfg(feature = "pnm")]
+        ImageFormat::Pgm => Box::new(
+            pnm::PnmEncoder::new(buffered_write)
+                .with_subtype(pnm::PnmSubtype::Graymap(pnm::SampleEncoding::Binary)),
+        ),
+        #[cfg(feature = "pnm")]
+        ImageFormat::Ppm => Box::new(
+            pnm::PnmEncoder::new(buffered_write)
+                .with_subtype(pnm::PnmSubtype::Pixmap(pnm::SampleEncoding::Binary)),
+        ),
+        #[cfg(feature = "pnm")]
+        ImageFormat::Pnm => {
+            Box::new(pnm::PnmEncoder::new(buffered_write).with_dynamic_pnm_header())
+        }
+        #[cfg(feature = "pnm")]
+        ImageFormat::Pam => Box::new(
+            pnm::PnmEncoder::new(buffered_write).with_subtype(pnm::PnmSubtype::ArbitraryMap),
+        ),
         #[cfg(feature = "gif")]
         ImageFormat::Gif => Box::new(gif::GifEncoder::new(buffered_write)),
         #[cfg(feature = "ico")]
@@ -120,13 +141,13 @@ static MAGIC_BYTES: [(&[u8], &[u8], ImageFormat); 21] = [
     (b"\0\0\0\0ftypavif", b"\xFF\xFF\0\0", ImageFormat::Avif),
     (&[0x76, 0x2f, 0x31, 0x01], b"", ImageFormat::OpenExr), // = &exr::meta::magic_number::BYTES
     (b"qoif", b"", ImageFormat::Qoi),
-    (b"P1", b"", ImageFormat::Pnm),
-    (b"P2", b"", ImageFormat::Pnm),
-    (b"P3", b"", ImageFormat::Pnm),
-    (b"P4", b"", ImageFormat::Pnm),
-    (b"P5", b"", ImageFormat::Pnm),
-    (b"P6", b"", ImageFormat::Pnm),
-    (b"P7", b"", ImageFormat::Pnm),
+    (b"P1", b"", ImageFormat::Pbm),
+    (b"P2", b"", ImageFormat::Pgm),
+    (b"P3", b"", ImageFormat::Ppm),
+    (b"P4", b"", ImageFormat::Pbm),
+    (b"P5", b"", ImageFormat::Pgm),
+    (b"P6", b"", ImageFormat::Ppm),
+    (b"P7", b"", ImageFormat::Pam),
     (b"farbfeld", b"", ImageFormat::Farbfeld),
 ];
 
@@ -193,13 +214,15 @@ fn test_guess_format_agrees_with_extension() {
     for fmt in ImageFormat::all() {
         use ImageFormat::*;
         let found = found.contains(&fmt);
-        if matches!(
-            fmt,
-            Bmp | Farbfeld | Gif | Ico | Hdr | Jpeg | OpenExr | Png | Pnm | Qoi | Tiff | WebP
-        ) {
-            assert!(found, "No {fmt:?} test files found");
-        } else {
-            assert!(!found, "Add `{fmt:?}` to test_guess_format");
+        match fmt {
+            Pnm => (), // Pnm images are always detected as one of Pbm, Pgm, Ppm
+            Bmp | Farbfeld | Gif | Ico | Hdr | Jpeg | OpenExr | Png | Pbm | Pgm | Ppm | Pam
+            | Qoi | Tiff | WebP => {
+                assert!(found, "No {fmt:?} test files found");
+            }
+            _ => {
+                assert!(!found, "Add `{fmt:?}` to test_guess_format");
+            }
         }
     }
 

src/io/image_reader_type.rs

@@ -48,7 +48,7 @@ enum Format {
 ///
 /// It is also possible to make a guess based on the content. This is especially handy if the
 /// source is some blob in memory and you have constructed the reader in another way. Here is an
-/// example with a `pnm` black-and-white subformat that encodes its pixel matrix with ascii values.
+/// example with a `pbm` black-and-white subformat that encodes its pixel matrix with ascii values.
 ///
 /// ```
 /// # use image::ImageError;
@@ -64,7 +64,7 @@ enum Format {
 /// let mut reader = ImageReader::new(Cursor::new(raw_data))
 ///     .with_guessed_format()
 ///     .expect("Cursor io never fails");
-/// assert_eq!(reader.format(), Some(ImageFormat::Pnm));
+/// assert_eq!(reader.format(), Some(ImageFormat::Pbm));
 ///
 /// # #[cfg(feature = "pnm")]
 /// let image = reader.decode()?;
@@ -224,7 +224,11 @@ impl<'a, R: 'a + BufRead + Seek> ImageReader<R> {
             #[cfg(feature = "exr")]
             ImageFormat::OpenExr => Box::new(openexr::OpenExrDecoder::new(reader)?),
             #[cfg(feature = "pnm")]
-            ImageFormat::Pnm => Box::new(pnm::PnmDecoder::new(reader)?),
+            ImageFormat::Pbm
+            | ImageFormat::Pgm
+            | ImageFormat::Ppm
+            | ImageFormat::Pnm
+            | ImageFormat::Pam => Box::new(pnm::PnmDecoder::new(reader)?),
             #[cfg(feature = "ff")]
             ImageFormat::Farbfeld => Box::new(farbfeld::FarbfeldDecoder::new(reader)?),
             #[cfg(feature = "qoi")]

src/lib.rs

@@ -199,22 +199,22 @@ pub use crate::images::flat;
 ///
 /// # Supported formats
 ///
-/// | Feature | Format   | Notes
-/// | ------- | -------- | -----
-/// | `avif`  | AVIF     | Decoding requires the `avif-native` feature, uses the libdav1d C library.
-/// | `bmp`   | BMP      |
-/// | `exr`   | OpenEXR  |
-/// | `ff`    | Farbfeld |
-/// | `gif`   | GIF      |
-/// | `hdr`   | HDR      |
-/// | `ico`   | ICO      |
-/// | `jpeg`  | JPEG     |
-/// | `png`   | PNG      |
-/// | `pnm`   | PNM      |
-/// | `qoi`   | QOI      |
-/// | `tga`   | TGA      |
-/// | `tiff`  | TIFF     |
-/// | `webp`  | WebP     | Only lossless encoding is currently supported.
+/// | Feature | Format(s)               | Notes
+/// | ------- | ----------------------- | -----
+/// | `avif`  | AVIF                    | Decoding requires the `avif-native` feature, uses the libdav1d C library.
+/// | `bmp`   | BMP                     |
+/// | `exr`   | OpenEXR                 |
+/// | `ff`    | Farbfeld                |
+/// | `gif`   | GIF                     |
+/// | `hdr`   | HDR                     |
+/// | `ico`   | ICO                     |
+/// | `jpeg`  | JPEG                    |
+/// | `png`   | PNG                     |
+/// | `pnm`   | PBM, PGM, PPM, PNM, PAM |
+/// | `qoi`   | QOI                     |
+/// | `tga`   | TGA                     |
+/// | `tiff`  | TIFF                    |
+/// | `webp`  | WebP                    | Only lossless encoding is currently supported.
 ///
 /// ## A note on format specific features
 ///

tests/images/pnm/pbm/l1a.pbm

@@ -0,0 +1,3 @@
+P1	
+ 9 7 1001100010110101	100110101100000100010
+ 110101100110 10110011010001

tests/images/pnm/pgm/l16a.pgm

@@ -0,0 +1,6 @@
+P2
+9 7 1285
+0 1014 1019 15 20 1254 1254 1254 41 969 70 75 985 86 1206 96 101 1217 
+930 136 141 946 151 1158 162 167 1181 891 896 902 907 217 1111 1132 
+1143 238 852 267 272 868 283 1063 293 298 1108 813 333 338 829 348 
+1015 359 364 1072 774 399 404 790 414 968 1010 1033 435 

tests/images/pnm/pgm/l8a.pgm

@@ -0,0 +1,3 @@
+P2	9 7 85 0 67 67 1 1 83 83 83 2 64 4 5 65 5 79 6 6 80 61 9 9 62 10 76 10 11 78 
+59 59 59 60 14 73 75 75 15 56 17 18 57 18 70 19 19 73 53 22 22 55 23 
+67 23 24 71 51 26 26 52 27 64 67 68 28 

tests/images/pnm/ppm/r16a.ppm

@@ -0,0 +1,16 @@
+P3 # Comment
+# This is a comment
+9 7 # This too
+3855
+0 0 0 3855 2891 2141 3855 2891 2355 0 0 642 0 0 856 3855 3855 2570 
+3855 3855 2570 3855 3855 2570 0 0 1713 3304 2891 1927 0 275 214 0 275 
+428 3304 2891 2570 0 275 856 3549 3746 2570 0 275 1285 0 275 1499 3365
+ 3848 2570 2753 2891 1927 0 550 214 0 550 428 2753 2891 2570 0 550 856
+ 3243 3637 2570 0 550 1285 0 550 1499 2875 3841 2570 2202 2891 1927 
+2202 2891 2141 2202 2891 2355 2202 2891 2570 0 826 856 2937 3528 2570 
+2753 3671 2570 2570 3773 2570 0 826 1713 1652 2891 1927 0 1101 214 0 
+1101 428 1652 2891 2570 0 1101 856 2631 3419 2570 0 1101 1285 0 1101 
+1499 1896 3827 2570 1101 2891 1927 0 1376 214 0 1376 428 1101 2891 
+2570 0 1376 856 2325 3311 2570 0 1376 1285 0 1376 1499 1407 3821 2570 
+550 2891 1927 0 1652 214 0 1652 428 550 2891 2570 0 1652 856 2019 3202
+ 2570 1652 3487 2570 1285 3691 2570 0 1652 1713 

tests/images/pnm/ppm/r8a.ppm

@@ -0,0 +1,10 @@
+P3
+9 7 51
+0 0 0 51 38 28 51 38 31 0 0 8 0 0 11 51 51 34 51 51 34 51 51 34 0 0 22
+ 43 38 25 0 3 2 0 3 5 43 38 34 0 3 11 47 49 34 0 3 17 0 3 19 44 51 34 
+36 38 25 0 7 2 0 7 5 36 38 34 0 7 11 43 48 34 0 7 17 0 7 19 38 50 34 
+29 38 25 29 38 28 29 38 31 29 38 34 0 11 11 38 46 34 36 48 34 34 50 34
+ 0 11 22 21 38 25 0 14 2 0 14 5 21 38 34 0 14 11 34 45 34 0 14 17 0 14
+ 19 25 50 34 14 38 25 0 18 2 0 18 5 14 38 34 0 18 11 30 43 34 0 18 17 
+0 18 19 18 50 34 7 38 25 0 21 2 0 21 5 7 38 34 0 21 11 26 42 34 21 46 
+34 17 48 34 0 21 22