Debian Codegraph @

.cargo/vendor/image/README.md

raw
1 # Image
2 [![crates.io](https://img.shields.io/crates/v/image.svg)](https://crates.io/crates/image)
3 [![Documentation](https://docs.rs/image/badge.svg)](https://docs.rs/image)
4 [![Build Status](https://github.com/image-rs/image/workflows/Rust%20CI/badge.svg)](https://github.com/image-rs/image/actions)
5 [![Gitter](https://badges.gitter.im/image-rs/image.svg)](https://gitter.im/image-rs/image?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
6
7 Maintainers: [@197g](https://github.com/197g), [@fintelia](https://github.com/fintelia)
8
9 [How to contribute](https://github.com/image-rs/organization/blob/master/CONTRIBUTING.md)
10
11 ## An Image Processing Library
12
13 This crate provides basic image processing functions and methods for converting to and from various image formats.
14
15 All image processing functions provided operate on types that implement the `GenericImageView` and `GenericImage` traits and return an `ImageBuffer`.
16
17 ## High level API
18
19 Load images using [`ImageReader`]:
20
21 ```rust,ignore
22 use std::io::Cursor;
23 use image::ImageReader;
24
25 let img = ImageReader::open("myimage.png")?.decode()?;
26 let img2 = ImageReader::new(Cursor::new(bytes)).with_guessed_format()?.decode()?;
27 ```
28
29 And save them using [`save`] or [`write_to`] methods:
30
31 ```rust,ignore
32 img.save("empty.jpg")?;
33
34 let mut bytes: Vec<u8> = Vec::new();
35 img2.write_to(&mut Cursor::new(&mut bytes), image::ImageFormat::Png)?;
36 ```
37
38 ## Supported Image Formats
39
40 With default features enabled, `image` provides implementations of [many common
41 image format encoders and decoders.](https://docs.rs/image/latest/image/codecs/index.html#supported-formats)
42
43 Decoding support for additional image formats is provided by
44 [`image-extras`](https://github.com/image-rs/image-extras), and the same plugin
45 interface lets third-party crates act as format implementations for `image`. If
46 you need to handle some other image format, check crates.io for crates that
47 implement it.
48
49 ## Feature Flags
50
51 | Feature | Description
52 | ----------------- | -----------
53 | `default-formats` | **Default**<br>Format support for common image formats: AVIF, BMP, DDS, EXR, FF, GIF, HDR, ICO, JPEG, PNG, PNM, QOI, TGA, TIFF, and WebP
54 | `rayon` | **Default**<br>Enables multi-threading with rayon context in some dependencies
55 | `nasm` | Enables the build-time use of `nasm` for `ravif`, requires `nasm` installed
56 | `color_quant` | Includes `color_quant` as an implementation of `imageops::ColorMap`
57 | `avif-native` | Enables non-Rust dependencies of `avif` (`mp4parse` and `dav1d`)
58 | `serde` | Enables `serde` integration for various structs and options
59
60 Note: When using `image` in a library you intend to publish, it is recommended to set `default-features = false` and then explicitly enable format features that are absolutely necessary. This ensures a smaller dependency tree and faster iteration time. The default feature configuration would also enable multithreading which may cause unexpected behavior when running for inherently single-threaded environments such as `wasm` targets.
61
62 ## Image Types
63
64 This crate provides a number of different types for representing images.
65 Individual pixels within images are indexed with (0,0) at the top left corner.
66
67 ### [`ImageBuffer`](https://docs.rs/image/*/image/struct.ImageBuffer.html)
68 An image parameterised by its Pixel type, represented by a width and height and
69 a vector of pixels. It provides direct access to its pixels and implements the
70 `GenericImageView` and `GenericImage` traits.
71
72 ### [`DynamicImage`](https://docs.rs/image/*/image/enum.DynamicImage.html)
73 A `DynamicImage` is an enumeration over all supported `ImageBuffer<P>` types.
74 Its exact image type is determined at runtime. It is the type returned when
75 opening an image. For convenience `DynamicImage` reimplements all image
76 processing functions.
77
78 ### The [`GenericImageView`](https://docs.rs/image/*/image/trait.GenericImageView.html) and [`GenericImage`](https://docs.rs/image/*/image/trait.GenericImage.html) Traits
79
80 Traits that provide methods for inspecting (`GenericImageView`) and manipulating (`GenericImage`) images, parameterised over the image's pixel type.
81
82 ### [`SubImage`](https://docs.rs/image/*/image/struct.SubImage.html)
83 A view into another image, delimited by the coordinates of a rectangle.
84 The coordinates given set the position of the top left corner of the rectangle.
85 This is used to perform image processing functions on a subregion of an image.
86
87
88 ## The [`ImageDecoder`](https://docs.rs/image/*/image/trait.ImageDecoder.html) and [`ImageDecoderRect`](https://docs.rs/image/*/image/trait.ImageDecoderRect.html) Traits
89
90 All image format decoders implement the `ImageDecoder` trait which provide
91 basic methods for getting image metadata and decoding images. Some formats
92 additionally provide `ImageDecoderRect` implementations which allow for
93 decoding only part of an image at once.
94
95 The most important methods for decoders are...
96 + **dimensions**: Return a tuple containing the width and height of the image.
97 + **color_type**: Return the color type of the image data produced by this decoder.
98 + **read_image**: Decode the entire image into a slice of bytes.
99
100 ## Pixels
101
102 `image` provides the following pixel types:
103 + **Rgb**: RGB pixel
104 + **Rgba**: RGB with alpha (RGBA pixel)
105 + **Luma**: Grayscale pixel
106 + **LumaA**: Grayscale with alpha
107
108 All pixels are parameterised by their component type.
109
110 ## Image Processing Functions
111
112 These are the functions defined in the [`imageops`](https://docs.rs/image/latest/image/imageops/index.html) module. All functions operate on types that implement the [`GenericImage`](https://docs.rs/image/latest/image/trait.GenericImage.html) trait.
113 Note that some of the functions are very slow in debug mode. Make sure to use release mode if you experience any performance issues.
114
115 + [**blur**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.blur): Performs a Gaussian blur on the supplied image.
116 + [**brighten**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.brighten): Brighten the supplied image.
117 + [**huerotate**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.huerotate): Hue rotate the supplied image by degrees.
118 + [**contrast**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.adjust_contrast): Adjust the contrast of the supplied image.
119 + [**crop**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.crop): Return a mutable view into an image.
120 + [**filter3x3**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.filter3x3): Perform a 3x3 box filter on the supplied image.
121 + [**flip_horizontal**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.fliph): Flip an image horizontally.
122 + [**flip_vertical**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.flipv): Flip an image vertically.
123 + [**grayscale**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.grayscale): Convert the supplied image to grayscale.
124 + [**invert**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.invert): Invert each pixel within the supplied image This function operates in place.
125 + [**resize**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.resize): Resize the supplied image to the specified dimensions.
126 + [**rotate180**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.rotate180): Rotate an image 180 degrees clockwise.
127 + [**rotate270**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.rotate270): Rotate an image 270 degrees clockwise.
128 + [**rotate90**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.rotate90): Rotate an image 90 degrees clockwise.
129 + [**unsharpen**](https://docs.rs/image/latest/image/enum.DynamicImage.html#method.unsharpen): Performs an unsharpen mask on the supplied image.
130
131 For more options, see the [`imageproc`](https://crates.io/crates/imageproc) crate.
132
133 ## Examples
134 ### Opening and Saving Images
135
136 `image` provides the [`open`](https://docs.rs/image/latest/image/fn.open.html) function for opening images from a path. The image
137 format is determined from the path's file extension. An `io` module provides a
138 reader which offer some more control.
139
140 ```rust,no_run
141 use image::GenericImageView;
142
143 // Use the open function to load an image from a Path.
144 // `open` returns a `DynamicImage` on success.
145 let img = image::open("tests/images/jpg/progressive/cat.jpg").unwrap();
146
147 // The dimensions method returns the images width and height.
148 println!("dimensions {:?}", img.dimensions());
149
150 // The color method returns the image's `ColorType`.
151 println!("{:?}", img.color());
152
153 // Write the contents of this image to the Writer in PNG format.
154 img.save("test.png").unwrap();
155 ```
156
157 ### Generating Fractals
158
159 ```rust,no_run
160 //! An example of generating julia fractals.
161 let imgx = 800;
162 let imgy = 800;
163
164 let scalex = 3.0 / imgx as f32;
165 let scaley = 3.0 / imgy as f32;
166
167 // Create a new ImgBuf with width: imgx and height: imgy
168 let mut imgbuf = image::ImageBuffer::new(imgx, imgy);
169
170 // Iterate over the coordinates and pixels of the image
171 for (x, y, pixel) in imgbuf.enumerate_pixels_mut() {
172 let r = (0.3 * x as f32) as u8;
173 let b = (0.3 * y as f32) as u8;
174 *pixel = image::Rgb([r, 0, b]);
175 }
176
177 // A redundant loop to demonstrate reading image data
178 for x in 0..imgx {
179 for y in 0..imgy {
180 let cx = y as f32 * scalex - 1.5;
181 let cy = x as f32 * scaley - 1.5;
182
183 let c = num_complex::Complex::new(-0.4, 0.6);
184 let mut z = num_complex::Complex::new(cx, cy);
185
186 let mut i = 0;
187 while i < 255 && z.norm() <= 2.0 {
188 z = z * z + c;
189 i += 1;
190 }
191
192 let pixel = imgbuf.get_pixel_mut(x, y);
193 let image::Rgb(data) = *pixel;
194 *pixel = image::Rgb([data[0], i as u8, data[2]]);
195 }
196 }
197
198 // Save the image as “fractal.png”, the format is deduced from the path
199 imgbuf.save("fractal.png").unwrap();
200 ```
201
202 Example output:
203
204 <img src="examples/fractal.png" alt="A Julia Fractal, c: -0.4 + 0.6i" width="500" />
205
206 ### Writing raw buffers
207 If the high level interface is not needed because the image was obtained by other means, `image` provides the function [`save_buffer`](https://docs.rs/image/latest/image/fn.save_buffer.html) to save a buffer to a file.
208
209 ```rust,no_run
210 let buffer: &[u8] = unimplemented!(); // Generate the image data
211
212 // Save the buffer as "image.png"
213 image::save_buffer("image.png", buffer, 800, 600, image::ExtendedColorType::Rgb8).unwrap()
214 ```