From 2f7eb0ba790a29f4aacf09d93182f5eb05cc06cc Mon Sep 17 00:00:00 2001
From: "Sergey \"Shnatsel\" Davidoff" <shnatsel@gmail.com>
Date: Sat, 14 Sep 2024 19:30:33 +0100
Subject: [PATCH] Add Exif orientation example in a doc comment (#2326)

---
 Cargo.toml      |  1 +
 src/dynimage.rs | 34 +++++++++++++++++++++++++++++++---
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index c00e79ca6e..e5e19ee5db 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -62,6 +62,7 @@ num-complex = "0.4"
 glob = "0.3"
 quickcheck = "1"
 criterion = "0.5.0"
+kamadak-exif = "0.5.5"
 
 [features]
 default = ["rayon", "default-formats"]
diff --git a/src/dynimage.rs b/src/dynimage.rs
index 923eb1f0c7..dbcc7a3bb5 100644
--- a/src/dynimage.rs
+++ b/src/dynimage.rs
@@ -874,7 +874,7 @@ impl DynamicImage {
 
     /// Flip this image vertically
     ///
-    /// Use [`apply_orientation`](Self::apply_orientation) of you want to flip the image in-place instead.
+    /// Use [`apply_orientation`](Self::apply_orientation) if you want to flip the image in-place instead.
     #[must_use]
     pub fn flipv(&self) -> DynamicImage {
         dynamic_map!(*self, ref p => imageops::flip_vertical(p))
@@ -887,7 +887,7 @@ impl DynamicImage {
 
     /// Flip this image horizontally
     ///
-    /// Use [`apply_orientation`](Self::apply_orientation) of you want to flip the image in-place.
+    /// Use [`apply_orientation`](Self::apply_orientation) if you want to flip the image in-place.
     #[must_use]
     pub fn fliph(&self) -> DynamicImage {
         dynamic_map!(*self, ref p => imageops::flip_horizontal(p))
@@ -906,7 +906,7 @@ impl DynamicImage {
 
     /// Rotate this image 180 degrees.
     ///
-    /// Use [`apply_orientation`](Self::apply_orientation) of you want to rotate the image in-place.
+    /// Use [`apply_orientation`](Self::apply_orientation) if you want to rotate the image in-place.
     #[must_use]
     pub fn rotate180(&self) -> DynamicImage {
         dynamic_map!(*self, ref p => imageops::rotate180(p))
@@ -925,6 +925,34 @@ impl DynamicImage {
 
     /// Rotates and/or flips the image as indicated by [Orientation].
     ///
+    /// This can be used to apply Exif orientation to an image,
+    /// e.g. to correctly display a photo taken by a smartphone camera:
+    ///
+    /// ```
+    /// # fn only_check_if_this_compiles() -> Result<(), Box<dyn std::error::Error>> {
+    /// # use image::{Orientation, DynamicImage, ImageReader, ImageDecoder};
+    /// use exif::{In, Tag}; // third-party crate `kamadak_exif` is needed to parse Exif chunk
+    ///
+    /// let mut decoder = ImageReader::open("file.jpg")?.into_decoder()?;
+    /// let raw_exif = decoder.exif_metadata();
+    /// let mut image = DynamicImage::from_decoder(decoder)?;
+    ///
+    /// // Parse Exif chunk (if present) and apply the orientation
+    /// if let Ok(Some(raw_exif)) = raw_exif {
+    ///     let reader = exif::Reader::new();
+    ///     let exif = reader.read_raw(raw_exif)?;
+    ///     if let Some(orientation) = exif.get_field(Tag::Orientation, In::PRIMARY) {
+    ///        if let Some(value) = orientation.value.get_uint(0) {
+    ///            if let Some(orientation) = Orientation::from_exif(value as u8) {
+    ///                image.apply_orientation(orientation);
+    ///            }
+    ///        }
+    ///    }
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
     /// Note that for some orientations cannot be efficiently applied in-place.
     /// In that case this function will make a copy of the image internally.
     ///