| 1 |
//! # Overview |
| 2 |
//! |
| 3 |
//! This crate provides native rust implementations of image encoding and decoding as well as some |
| 4 |
//! basic image manipulation functions. Additional documentation can currently also be found in the |
| 5 |
//! [README.md file which is most easily viewed on |
| 6 |
//! github](https://github.com/image-rs/image/blob/main/README.md). |
| 7 |
//! |
| 8 |
//! There are two core problems for which this library provides solutions: a unified interface for image |
| 9 |
//! encodings and simple generic buffers for their content. It's possible to use either feature |
| 10 |
//! without the other. The focus is on a small and stable set of common operations that can be |
| 11 |
//! supplemented by other specialized crates. The library also prefers safe solutions with few |
| 12 |
//! dependencies. |
| 13 |
//! |
| 14 |
//! # High level API |
| 15 |
//! |
| 16 |
//! Load images using [`ImageReader`](crate::ImageReader): |
| 17 |
//! |
| 18 |
//! ```rust,no_run |
| 19 |
//! use std::io::Cursor; |
| 20 |
//! use image::ImageReader; |
| 21 |
//! # fn main() -> Result<(), image::ImageError> { |
| 22 |
//! # let bytes = vec![0u8]; |
| 23 |
//! |
| 24 |
//! let img = ImageReader::open("myimage.png")?.decode()?; |
| 25 |
//! let img2 = ImageReader::new(Cursor::new(bytes)).with_guessed_format()?.decode()?; |
| 26 |
//! # Ok(()) |
| 27 |
//! # } |
| 28 |
//! ``` |
| 29 |
//! |
| 30 |
//! And save them using [`save`] or [`write_to`] methods: |
| 31 |
//! |
| 32 |
//! ```rust,no_run |
| 33 |
//! # use std::io::{Write, Cursor}; |
| 34 |
//! # use image::{DynamicImage, ImageFormat}; |
| 35 |
//! # #[cfg(feature = "png")] |
| 36 |
//! # fn main() -> Result<(), image::ImageError> { |
| 37 |
//! # let img: DynamicImage = unimplemented!(); |
| 38 |
//! # let img2: DynamicImage = unimplemented!(); |
| 39 |
//! img.save("empty.jpg")?; |
| 40 |
//! |
| 41 |
//! let mut bytes: Vec<u8> = Vec::new(); |
| 42 |
//! img2.write_to(&mut Cursor::new(&mut bytes), image::ImageFormat::Png)?; |
| 43 |
//! # Ok(()) |
| 44 |
//! # } |
| 45 |
//! # #[cfg(not(feature = "png"))] fn main() {} |
| 46 |
//! ``` |
| 47 |
//! |
| 48 |
//! With default features, the crate includes support for [many common image formats](codecs/index.html#supported-formats). |
| 49 |
//! |
| 50 |
//! [`save`]: enum.DynamicImage.html#method.save |
| 51 |
//! [`write_to`]: enum.DynamicImage.html#method.write_to |
| 52 |
//! [`ImageReader`]: struct.Reader.html |
| 53 |
//! |
| 54 |
//! # Image buffers |
| 55 |
//! |
| 56 |
//! The two main types for storing images: |
| 57 |
//! * [`ImageBuffer`] which holds statically typed image contents. |
| 58 |
//! * [`DynamicImage`] which is an enum over the supported `ImageBuffer` formats |
| 59 |
//! and supports conversions between them. |
| 60 |
//! |
| 61 |
//! As well as a few more specialized options: |
| 62 |
//! * [`GenericImage`] trait for a mutable image buffer. |
| 63 |
//! * [`GenericImageView`] trait for read only references to a `GenericImage`. |
| 64 |
//! * [`flat`] module containing types for interoperability with generic channel |
| 65 |
//! matrices and foreign interfaces. |
| 66 |
//! |
| 67 |
//! [`GenericImageView`]: trait.GenericImageView.html |
| 68 |
//! [`GenericImage`]: trait.GenericImage.html |
| 69 |
//! [`ImageBuffer`]: struct.ImageBuffer.html |
| 70 |
//! [`DynamicImage`]: enum.DynamicImage.html |
| 71 |
//! [`flat`]: flat/index.html |
| 72 |
//! |
| 73 |
//! # Low level encoding/decoding API |
| 74 |
//! |
| 75 |
//! Implementations of [`ImageEncoder`] provides low level control over encoding: |
| 76 |
//! ```rust,no_run |
| 77 |
//! # use std::io::Write; |
| 78 |
//! # use image::DynamicImage; |
| 79 |
//! # use image::ImageEncoder; |
| 80 |
//! # #[cfg(feature = "jpeg")] |
| 81 |
//! # fn main() -> Result<(), image::ImageError> { |
| 82 |
//! # use image::codecs::jpeg::JpegEncoder; |
| 83 |
//! # let img: DynamicImage = unimplemented!(); |
| 84 |
//! # let writer: Box<dyn Write> = unimplemented!(); |
| 85 |
//! let encoder = JpegEncoder::new_with_quality(&mut writer, 95); |
| 86 |
//! img.write_with_encoder(encoder)?; |
| 87 |
//! # Ok(()) |
| 88 |
//! # } |
| 89 |
//! # #[cfg(not(feature = "jpeg"))] fn main() {} |
| 90 |
//! ``` |
| 91 |
//! While [`ImageDecoder`] and [`ImageDecoderRect`] give access to more advanced decoding options: |
| 92 |
//! |
| 93 |
//! ```rust,no_run |
| 94 |
//! # use std::io::{BufReader, Cursor}; |
| 95 |
//! # use image::DynamicImage; |
| 96 |
//! # use image::ImageDecoder; |
| 97 |
//! # #[cfg(feature = "png")] |
| 98 |
//! # fn main() -> Result<(), image::ImageError> { |
| 99 |
//! # use image::codecs::png::PngDecoder; |
| 100 |
//! # let img: DynamicImage = unimplemented!(); |
| 101 |
//! # let reader: BufReader<Cursor<&[u8]>> = unimplemented!(); |
| 102 |
//! let decoder = PngDecoder::new(&mut reader)?; |
| 103 |
//! let icc = decoder.icc_profile(); |
| 104 |
//! let img = DynamicImage::from_decoder(decoder)?; |
| 105 |
//! # Ok(()) |
| 106 |
//! # } |
| 107 |
//! # #[cfg(not(feature = "png"))] fn main() {} |
| 108 |
//! ``` |
| 109 |
//! |
| 110 |
//! [`DynamicImage::from_decoder`]: enum.DynamicImage.html#method.from_decoder |
| 111 |
//! [`ImageDecoderRect`]: trait.ImageDecoderRect.html |
| 112 |
//! [`ImageDecoder`]: trait.ImageDecoder.html |
| 113 |
//! [`ImageEncoder`]: trait.ImageEncoder.html |
| 114 |
#![warn(missing_docs)] |
| 115 |
#![warn(unused_qualifications)] |
| 116 |
#![deny(unreachable_pub)] |
| 117 |
#![deny(deprecated)] |
| 118 |
#![deny(missing_copy_implementations)] |
| 119 |
#![cfg_attr(all(test, feature = "benchmarks"), feature(test))] |
| 120 |
#![cfg_attr(docsrs, feature(doc_cfg))] |
| 121 |
|
| 122 |
#[cfg(all(test, feature = "benchmarks"))] |
| 123 |
extern crate test; |
| 124 |
|
| 125 |
#[cfg(test)] |
| 126 |
#[macro_use] |
| 127 |
extern crate quickcheck; |
| 128 |
|
| 129 |
pub use crate::color::{ColorType, ExtendedColorType}; |
| 130 |
|
| 131 |
pub use crate::color::{Luma, LumaA, Rgb, Rgba}; |
| 132 |
|
| 133 |
pub use crate::error::{ImageError, ImageResult}; |
| 134 |
|
| 135 |
pub use crate::images::generic_image::{GenericImage, GenericImageView, Pixels}; |
| 136 |
|
| 137 |
pub use crate::images::sub_image::SubImage; |
| 138 |
|
| 139 |
pub use crate::images::buffer::{ |
| 140 |
ConvertColorOptions, |
| 141 |
GrayAlphaImage, |
| 142 |
GrayImage, |
| 143 |
// Image types |
| 144 |
ImageBuffer, |
| 145 |
Rgb32FImage, |
| 146 |
RgbImage, |
| 147 |
Rgba32FImage, |
| 148 |
RgbaImage, |
| 149 |
}; |
| 150 |
|
| 151 |
pub use crate::flat::FlatSamples; |
| 152 |
|
| 153 |
// Traits |
| 154 |
pub use crate::traits::{EncodableLayout, Pixel, PixelWithColorType, Primitive}; |
| 155 |
|
| 156 |
// Opening and loading images |
| 157 |
pub use crate::images::dynimage::{ |
| 158 |
image_dimensions, load_from_memory, load_from_memory_with_format, open, |
| 159 |
write_buffer_with_format, |
| 160 |
}; |
| 161 |
pub use crate::io::free_functions::{guess_format, load, save_buffer, save_buffer_with_format}; |
| 162 |
|
| 163 |
pub use crate::io::{ |
| 164 |
decoder::{AnimationDecoder, ImageDecoder, ImageDecoderRect}, |
| 165 |
encoder::ImageEncoder, |
| 166 |
format::ImageFormat, |
| 167 |
image_reader_type::ImageReader, |
| 168 |
limits::{LimitSupport, Limits}, |
| 169 |
}; |
| 170 |
|
| 171 |
pub use crate::images::dynimage::DynamicImage; |
| 172 |
|
| 173 |
pub use crate::animation::{Delay, Frame, Frames}; |
| 174 |
|
| 175 |
// More detailed error type |
| 176 |
pub mod error; |
| 177 |
|
| 178 |
/// Iterators and other auxiliary structure for the `ImageBuffer` type. |
| 179 |
pub mod buffer { |
| 180 |
// Only those not exported at the top-level |
| 181 |
pub use crate::images::buffer::{ |
| 182 |
ConvertBuffer, EnumeratePixels, EnumeratePixelsMut, EnumerateRows, EnumerateRowsMut, |
| 183 |
Pixels, PixelsMut, Rows, RowsMut, |
| 184 |
}; |
| 185 |
|
| 186 |
#[cfg(feature = "rayon")] |
| 187 |
pub use crate::images::buffer_par::*; |
| 188 |
} |
| 189 |
|
| 190 |
// Math utils |
| 191 |
pub mod math; |
| 192 |
|
| 193 |
// Image processing functions |
| 194 |
pub mod imageops; |
| 195 |
|
| 196 |
// Buffer representations for ffi. |
| 197 |
pub use crate::images::flat; |
| 198 |
|
| 199 |
/// Encoding and decoding for various image file formats. |
| 200 |
/// |
| 201 |
/// # Supported formats |
| 202 |
/// |
| 203 |
/// | Feature | Format | Notes |
| 204 |
/// | ------- | -------- | ----- |
| 205 |
/// | `avif` | AVIF | Decoding requires the `avif-native` feature, uses the libdav1d C library. |
| 206 |
/// | `bmp` | BMP | |
| 207 |
/// | `dds` | DDS | Only decoding is supported. |
| 208 |
/// | `exr` | OpenEXR | |
| 209 |
/// | `ff` | Farbfeld | |
| 210 |
/// | `gif` | GIF | |
| 211 |
/// | `hdr` | HDR | |
| 212 |
/// | `ico` | ICO | |
| 213 |
/// | `jpeg` | JPEG | |
| 214 |
/// | `png` | PNG | |
| 215 |
/// | `pnm` | PNM | |
| 216 |
/// | `qoi` | QOI | |
| 217 |
/// | `tga` | TGA | |
| 218 |
/// | `tiff` | TIFF | |
| 219 |
/// | `webp` | WebP | Only lossless encoding is currently supported. |
| 220 |
/// |
| 221 |
/// ## A note on format specific features |
| 222 |
/// |
| 223 |
/// One of the main goals of `image` is stability, in runtime but also for programmers. This |
| 224 |
/// ensures that performance as well as safety fixes reach a majority of its user base with little |
| 225 |
/// effort. Re-exporting all details of its dependencies would run counter to this goal as it |
| 226 |
/// linked _all_ major version bumps between them and `image`. As such, we are wary of exposing too |
| 227 |
/// many details, or configuration options, that are not shared between different image formats. |
| 228 |
/// |
| 229 |
/// Nevertheless, the advantage of precise control is hard to ignore. We will thus consider |
| 230 |
/// _wrappers_, not direct re-exports, in either of the following cases: |
| 231 |
/// |
| 232 |
/// 1. A standard specifies that configuration _x_ is required for decoders/encoders and there |
| 233 |
/// exists an essentially canonical way to control it. |
| 234 |
/// 2. At least two different implementations agree on some (sub-)set of features in practice. |
| 235 |
/// 3. A technical argument including measurements of the performance, space benefits, or otherwise |
| 236 |
/// objectively quantified benefits can be made, and the added interface is unlikely to require |
| 237 |
/// breaking changes. |
| 238 |
/// |
| 239 |
/// Features that fulfill two or more criteria are preferred. |
| 240 |
/// |
| 241 |
/// Re-exports of dependencies that reach version `1` will be discussed when it happens. |
| 242 |
pub mod codecs { |
| 243 |
#[cfg(any(feature = "avif", feature = "avif-native"))] |
| 244 |
pub mod avif; |
| 245 |
#[cfg(feature = "bmp")] |
| 246 |
pub mod bmp; |
| 247 |
#[cfg(feature = "dds")] |
| 248 |
pub mod dds; |
| 249 |
#[cfg(feature = "ff")] |
| 250 |
pub mod farbfeld; |
| 251 |
#[cfg(feature = "gif")] |
| 252 |
pub mod gif; |
| 253 |
#[cfg(feature = "hdr")] |
| 254 |
pub mod hdr; |
| 255 |
#[cfg(feature = "ico")] |
| 256 |
pub mod ico; |
| 257 |
#[cfg(feature = "jpeg")] |
| 258 |
pub mod jpeg; |
| 259 |
#[cfg(feature = "exr")] |
| 260 |
pub mod openexr; |
| 261 |
#[cfg(feature = "png")] |
| 262 |
pub mod png; |
| 263 |
#[cfg(feature = "pnm")] |
| 264 |
pub mod pnm; |
| 265 |
#[cfg(feature = "qoi")] |
| 266 |
pub mod qoi; |
| 267 |
#[cfg(feature = "tga")] |
| 268 |
pub mod tga; |
| 269 |
#[cfg(feature = "tiff")] |
| 270 |
pub mod tiff; |
| 271 |
#[cfg(feature = "webp")] |
| 272 |
pub mod webp; |
| 273 |
|
| 274 |
#[cfg(feature = "dds")] |
| 275 |
mod dxt; |
| 276 |
} |
| 277 |
|
| 278 |
mod animation; |
| 279 |
mod color; |
| 280 |
pub mod hooks; |
| 281 |
mod images; |
| 282 |
/// Deprecated io module the original io module has been renamed to `image_reader`. |
| 283 |
/// This is going to be internal. |
| 284 |
pub mod io; |
| 285 |
pub mod metadata; |
| 286 |
//TODO delete this module after a few releases |
| 287 |
mod traits; |
| 288 |
mod utils; |
| 289 |
|
| 290 |
// Can't use the macro-call itself within the `doc` attribute. So force it to eval it as part of |
| 291 |
// the macro invocation. |
| 292 |
// |
| 293 |
// The inspiration for the macro and implementation is from |
| 294 |
// <https://github.com/GuillaumeGomez/doc-comment> |
| 295 |
// |
| 296 |
// MIT License |
| 297 |
// |
| 298 |
// Copyright (c) 2018 Guillaume Gomez |
| 299 |
macro_rules! insert_as_doc { |
| 300 |
{ $content:expr } => { |
| 301 |
#[allow(unused_doc_comments)] |
| 302 |
#[doc = $content] extern "Rust" { } |
| 303 |
} |
| 304 |
} |
| 305 |
|
| 306 |
// Provides the README.md as doc, to ensure the example works! |
| 307 |
insert_as_doc!(include_str!("../README.md")); |