diff --git a/Cargo.toml b/Cargo.toml index c30a168..eb64113 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -10,7 +10,7 @@ homepage = "https://github.com/kamadak/exif-rs" repository = "https://github.com/kamadak/exif-rs" readme = "README" keywords = ["Exif", "JPEG", "parser", "reader", "TIFF"] -categories = ["multimedia::encoding", "parser-implementations"] +categories = ["multimedia::encoding", "multimedia::images", "parser-implementations"] license = "BSD-2-Clause" [dependencies] diff --git a/README b/README index ce4ea34..1281a50 100644 --- a/README +++ b/README @@ -2,8 +2,13 @@ Exif parsing library written in pure Rust ----------------------------------------- This is a pure-Rust library to parse Exif data. - This library can parse TIFF and JPEG images and extract Exif - attributes. + This library parses Exif attributes in a raw Exif data block. + It can also read Exif data directly from some image formats. + + Supported formats are: + - TIFF and some RAW image formats based on it + - JPEG + - HEIF and coding-specific variations including HEIC and AVIF Usage ----- diff --git a/src/lib.rs b/src/lib.rs index 18cf4b8..bf1e949 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -25,8 +25,10 @@ // //! This is a pure-Rust library to parse Exif data. -//! This library can parse TIFF and JPEG images and extract Exif -//! attributes. +//! +//! This library parses Exif attributes in a raw Exif data block. +//! It can also read Exif data directly from some image formats +//! including TIFF, JPEG, and HEIF. //! //! # Examples //! @@ -35,8 +37,9 @@ //! ``` //! for path in &["tests/exif.jpg", "tests/exif.tif"] { //! let file = std::fs::File::open(path).unwrap(); -//! let exif = exif::Reader::new().read_from_container( -//! &mut std::io::BufReader::new(&file)).unwrap(); +//! let mut bufreader = std::io::BufReader::new(&file); +//! let exifreader = exif::Reader::new(); +//! let exif = exifreader.read_from_container(&mut bufreader).unwrap(); //! for f in exif.fields() { //! println!("{} {} {}", //! f.tag, f.ifd_num, f.display_value().with_unit(&exif)); @@ -44,16 +47,48 @@ //! } //! ``` //! -//! # Upgrade Guide (0.3.x to 0.4.x) +//! # Upgrade Guide from 0.4.x to 0.5.x +//! +//! ## API compatibilities +//! +//! * `Reader` has been split into two: `Reader` and `Exif`. +//! `Reader` is now the builder for `Exif`, and `Exif` provides +//! access to `Field`s via `get_field`, `fields` and other methods. +//! Old code `Reader::new(data)` should be changed to +//! `Reader::new().read_raw(data)` or +//! `Reader::new().read_from_container(data)`. +//! +//! The old code using 0.4.x: +//! ```ignore +//! # use exif::Reader; +//! # let file = std::fs::File::open("tests/exif.jpg").unwrap(); +//! # let mut bufreader = std::io::BufReader::new(&file); +//! let reader = Reader::new(&mut bufreader).unwrap(); +//! for f in reader.fields() { /* do something */ } +//! ``` +//! The new code using 0.5.x: +//! ``` +//! # use exif::{Exif, Reader}; +//! # let file = std::fs::File::open("tests/exif.jpg").unwrap(); +//! # let mut bufreader = std::io::BufReader::new(&file); +//! let exif = Reader::new().read_from_container(&mut bufreader).unwrap(); +//! for f in exif.fields() { /* do something */ } +//! ``` +//! +//! ## Other new features +//! +//! * Support for parsing Exif in HEIF (HEIC/AVIF) has been added. +//! +//! # Upgrade Guide from 0.3.x to 0.4.x //! //! ## API compatibilities //! //! * Use struct `In` instead of `bool` to indicate primary/thumbnail images. -//! - On `Reader::get_field`, the old code in 0.3.x: +//! - On `Reader::get_field`, the old code using 0.3.x: //! ```ignore //! reader.get_field(Tag::DateTime, false) //! ``` -//! The new code in 0.4.x: +//! The new code using 0.4.x: //! ```ignore //! # use exif::{In, Reader, Tag}; //! # let file = std::fs::File::open("tests/exif.tif").unwrap(); @@ -63,7 +98,8 @@ //! # ; //! ``` //! As an additional feature, access to the 2nd or further IFD, -//! which some RAW formats may have, is also possible in 0.4.x: +//! which some TIFF-based RAW formats may have, is also possible +//! with 0.4.x: //! ```ignore //! # use exif::{In, Reader, Tag}; //! # let file = std::fs::File::open("tests/exif.tif").unwrap(); @@ -72,7 +108,7 @@ //! reader.get_field(Tag::ImageWidth, In(2)) //! # ; //! ``` -//! - On `Field`, the old code in 0.3.x: +//! - On `Field`, the old code using 0.3.x: //! ```ignore //! if field.thumbnail { //! // for the thumbnail image @@ -80,7 +116,7 @@ //! // for the primary image //! } //! ``` -//! The new code in 0.4.x: +//! The new code using 0.4.x: //! ``` //! # use exif::{In, Reader}; //! # let file = std::fs::File::open("tests/exif.tif").unwrap(); diff --git a/src/reader.rs b/src/reader.rs index c8963b2..45249dc 100644 --- a/src/reader.rs +++ b/src/reader.rs @@ -35,8 +35,8 @@ use crate::tag::Tag; use crate::tiff; use crate::tiff::{Field, IfdEntry, In, ProvideUnit}; -/// The `Reader` struct parses the Exif attributes and -/// returns `Exif` struct that holds the results. +/// A struct to parse the Exif attributes and +/// create an `Exif` instance that holds the results. /// /// # Examples /// ``` @@ -76,7 +76,10 @@ impl Reader { /// Reads an image file and parses the Exif attributes in it. /// If an error occurred, `exif::Error` is returned. /// - /// Supported formats are HEIF, JPEG, and TIFF. + /// Supported formats are: + /// - TIFF and some RAW image formats based on it + /// - JPEG + /// - HEIF and coding-specific variations including HEIC and AVIF /// /// This method is provided for the convenience even though /// parsing containers is basically out of the scope of this library. @@ -108,7 +111,7 @@ impl Reader { } } -/// The `Exif` struct holds the parsed Exif attributes. +/// A struct that holds the parsed Exif attributes. /// /// # Examples /// ``` @@ -151,7 +154,8 @@ impl Exif { .map(move |e| e.ref_field(&self.buf, self.little_endian)) } - /// Returns true if the TIFF data is in the little-endian byte order. + /// Returns true if the Exif data (TIFF structure) is in the + /// little-endian byte order. #[inline] pub fn little_endian(&self) -> bool { self.little_endian diff --git a/src/tag.rs b/src/tag.rs index 0c5e332..a2b2dd8 100644 --- a/src/tag.rs +++ b/src/tag.rs @@ -35,6 +35,9 @@ use crate::util::atou16; /// Some well-known tags are provided as associated constants of /// this type. The constant names follow the Exif specification /// but not the Rust naming conventions. +/// +/// A non-predefined tag can also be specified +/// by the context and the number as in `Tag(Context::Tiff, 0x100)`. // // This is not an enum to keep safety and API stability, while // supporting unknown tag numbers. This comment is based on the @@ -220,11 +223,13 @@ generate_well_known_tag_constants!( /// A pointer to the Exif IFD. This is used for the internal structure /// of Exif data and will not be returned to the user. + #[doc(hidden)] (ExifIFDPointer, 0x8769, DefaultValue::None, d_default, unit![], "Exif IFD pointer"), /// A pointer to the GPS IFD. This is used for the internal structure /// of Exif data and will not be returned to the user. + #[doc(hidden)] (GPSInfoIFDPointer, 0x8825, DefaultValue::None, d_default, unit![], "GPS Info IFD pointer"), @@ -233,6 +238,7 @@ generate_well_known_tag_constants!( /// A pointer to the interoperability IFD. This is used for the internal /// structure of Exif data and will not be returned to the user. + #[doc(hidden)] (InteropIFDPointer, 0xa005, DefaultValue::None, d_default, unit![], "Interoperability IFD pointer"), diff --git a/src/tiff.rs b/src/tiff.rs index a474111..166280c 100644 --- a/src/tiff.rs +++ b/src/tiff.rs @@ -379,7 +379,7 @@ impl Field { /// /// To print the value with the unit, call `with_unit` method on the /// returned object. It takes a parameter, which is either `()`, - /// `&Field`, or `&Exif` and provides the unit information. + /// `&Field`, or `&Exif`, that provides the unit information. /// If the unit does not depend on another field, `()` can be used. /// Otherwise, `&Field` or `&Exif` should be used. /// @@ -393,15 +393,15 @@ impl Field { /// ifd_num: In::PRIMARY, /// value: Value::Rational(vec![(72, 1).into()]), /// }; - /// let cm = Field { + /// let resunit = Field { /// tag: Tag::ResolutionUnit, /// ifd_num: In::PRIMARY, /// value: Value::Short(vec![3]), /// }; /// assert_eq!(xres.display_value().to_string(), "72"); - /// assert_eq!(cm.display_value().to_string(), "cm"); + /// assert_eq!(resunit.display_value().to_string(), "cm"); /// // The unit of XResolution is indicated by ResolutionUnit. - /// assert_eq!(xres.display_value().with_unit(&cm).to_string(), + /// assert_eq!(xres.display_value().with_unit(&resunit).to_string(), /// "72 pixels per cm"); /// // If ResolutionUnit is not given, the default value is used. /// assert_eq!(xres.display_value().with_unit(()).to_string(), @@ -416,8 +416,10 @@ impl Field { /// }; /// // The unit of the focal length is always mm, so the argument /// // has nothing to do with the result. - /// assert_eq!(flen.display_value().with_unit(()).to_string(), "24 mm"); - /// assert_eq!(flen.display_value().with_unit(&cm).to_string(), "24 mm"); + /// assert_eq!(flen.display_value().with_unit(()).to_string(), + /// "24 mm"); + /// assert_eq!(flen.display_value().with_unit(&resunit).to_string(), + /// "24 mm"); /// ``` #[inline] pub fn display_value(&self) -> DisplayValue {