michael/exif-rs
michael
/
exif-rs
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update the documentation for version 0.5.

This commit is contained in:
KAMADA Ken'ichi 2020-01-26 23:12:47 +09:00
parent 1d683572be
commit 60c8e15b11
6 changed files with 77 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Cargo.toml
View File

@ -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]

9
README
View File

@ -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
-----

56
src/lib.rs
View File

@ -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();

14
src/reader.rs
View File

@ -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

6
src/tag.rs
View File

@ -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"),

14
src/tiff.rs
View File

@ -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 {