| 1 |
# Image |
| 2 |
[](https://crates.io/crates/image) |
| 3 |
[](https://docs.rs/image) |
| 4 |
[](https://github.com/image-rs/image/actions) |
| 5 |
[](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 |
``` |