tiff_encoder/
lib.rs

1//! A crate for encoding TIFF files.
2//!
3//! This crate allows to create any hierarchy of IFDs and to add any
4//! tags with any values to each. It does so while avoiding that
5//! the user needs to worry about the position of each structure in the
6//! file and to point to it with the correct offset.
7//!
8//! The main structure of this crate, used to actually write the TIFF
9//! file, is the [`TiffFile`]. This structure writes the file in [little endian]
10//! by default (but that can be changed) and requires an [`IfdChain`]. This
11//! `IfdChain` consists of the first [`Ifd`] of the file, the one it points to (if any),
12//! and so on. Each `Ifd` has one or more entries, which are represented
13//! by a pair of [`FieldTag`] and [`FieldValues`].
14//!
15//! # Examples
16//!
17//! Creating a 256x256 bilevel image with every pixel black.
18//!
19//! ```
20//! #[macro_use]
21//! extern crate tiff_encoder;
22//! use tiff_encoder::prelude::*;
23//! use tiff_encoder::ifd::tags;
24//!
25//! # fn main() {
26//! // 256*256/8 = 8192
27//! // The image data will have 8192 bytes with 0 in every bit (each representing a
28//! // black pixel).
29//! let image_data = vec![0x00; 8192];
30//!
31//! TiffFile::new(
32//!     Ifd::new()
33//!         .with_entry(tags::PhotometricInterpretation, SHORT![1]) // Black is zero
34//!         .with_entry(tags::Compression, SHORT![1]) // No compression
35//!
36//!         .with_entry(tags::ImageLength, LONG![256])
37//!         .with_entry(tags::ImageWidth, LONG![256])
38//!
39//!         .with_entry(tags::ResolutionUnit, SHORT![1]) // No resolution unit
40//!         .with_entry(tags::XResolution, RATIONAL![(1, 1)])
41//!         .with_entry(tags::YResolution, RATIONAL![(1, 1)])
42//!
43//!         .with_entry(tags::RowsPerStrip, LONG![256]) // One strip for the whole image
44//!         .with_entry(tags::StripByteCounts, LONG![8192])
45//!         .with_entry(tags::StripOffsets, ByteBlock::single(image_data))
46//!         .single() // This is the only Ifd in its IfdChain
47//! ).write_to("example.tif").unwrap();
48//! # }
49//! ```
50//!
51//! [`TiffFile`]: struct.TiffFile.html
52//! [little endian]: write/enum.Endianness.html#variant.II
53//! [`Ifd`]: ifd/struct.Ifd.html
54//! [`IfdChain`]: ifd/struct.IfdChain.html
55//! [`FieldTag`]: ifd/tags/type.FieldTag.html
56//! [`FieldValues`]: ifd/values/trait.FieldValues.html
57
58extern crate byteorder;
59
60pub mod ifd;
61pub mod write;
62
63mod file;
64pub use file::TiffFile;
65
66/// Common imports that are necessary for almost every use of the `tiff_encoder`
67/// library.
68///
69/// # Usage
70/// ```
71/// use tiff_encoder::prelude::*;
72/// ```
73///
74/// # Other common imports
75///
76/// The following imports, although also often used for this library, are not
77/// included in the prelude to avoid polluting the user's namespace.
78///
79/// ```
80/// use tiff_encoder::write; // Helpers to write data to the file, particularly `Datablock`
81/// use tiff_encoder::ifd::tags; // Constants for common tags in IFD entries
82/// ```
83///
84/// Note that `macro_rules!` for using [`ifd::types`] cannot (unfortunately) be re-exported
85/// in the prelude. This means you'll either have to explicitely import them or use `#[macro_use]`.
86///
87/// ```
88/// // Either
89/// #[macro_use]
90/// extern crate tiff_encoder;
91///
92/// // Or
93/// use tiff_encoder::{
94///     ASCII, BYTE, DOUBLE, FLOAT, LONG, RATIONAL,
95///     SBYTE, SHORT, SLONG, SRATIONAL, SSHORT, UNDEFINED
96/// };
97///
98/// # fn main() {}
99/// ```
100///
101/// [`ifd::types`]: ../ifd/types/index.html
102pub mod prelude {
103    #[doc(no_inline)]
104    pub use crate::ifd::Ifd;
105    #[doc(no_inline)]
106    pub use crate::ifd::IfdChain;
107    #[doc(no_inline)]
108    pub use crate::write::ByteBlock;
109    #[doc(no_inline)]
110    pub use crate::TiffFile;
111}
tiff_encoder/lib.rs

tiff_encoder/
lib.rs
