Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_text/tests/annealer_corpus/image_lib.rs

9.7 KiB, 1 run

created by r1870400018:11740, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

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