Skip to content

Commit

Permalink
Update readme (#2155)
Browse files Browse the repository at this point in the history
  • Loading branch information
@fintelia
fintelia authored Feb 24, 2024
1 parent fe7f010 commit bfc509e
Show file tree
Hide file tree
Showing 3 changed files with 80 additions and 108 deletions.
5 changes: 1 addition & 4 deletions Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,6 @@ num-complex = "0.4"
glob = "0.3"
quickcheck = "1"
criterion = "0.5.0"
# Keep this in sync with the jpeg dependency above. This is used to enable the platform_independent
# feature when testing, so `cargo test` works correctly.
jpeg = { package = "jpeg-decoder", version = "0.3.0", default-features = false, features = ["platform_independent"] }

[features]
default = ["rayon", "default-formats"]
Expand All @@ -89,7 +86,7 @@ webp = ["dep:image-webp"]

# Other features
rayon = ["dep:rayon"] # Enables multi-threading
avif-native = ["dep:mp4parse", "dep:dcv-color-primitives", "dep:dav1d"] # Enable native dependency libdav1d (requires rustc 1.64.0)
avif-native = ["dep:mp4parse", "dep:dcv-color-primitives", "dep:dav1d"] # Enable native dependency libdav1d
benchmarks = [] # Build some inline benchmarks. Useful only during development (requires nightly Rust)

[[bench]]
Expand Down
147 changes: 60 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,33 +14,81 @@ This crate provides basic image processing functions and methods for converting

All image processing functions provided operate on types that implement the `GenericImageView` and `GenericImage` traits and return an `ImageBuffer`.

## High level API

Load images using [`io::Reader`]:

```rust,ignore
use std::io::Cursor;
use image::io::Reader as ImageReader;
let img = ImageReader::open("myimage.png")?.decode()?;
let img2 = ImageReader::new(Cursor::new(bytes)).with_guessed_format()?.decode()?;
```

And save them using [`save`] or [`write_to`] methods:

```rust,ignore
img.save("empty.jpg")?;
let mut bytes: Vec<u8> = Vec::new();
img2.write_to(&mut Cursor::new(&mut bytes), image::ImageFormat::Png)?;
```

## Supported Image Formats

`image` provides implementations of common image format encoders and decoders.
With default features enabled, `image` provides implementations of many common
image format encoders and decoders.

<!--- NOTE: Make sure to keep this table in sync with the one in src/lib.rs -->

| Format | Decoding | Encoding |
| -------- | ----------------------------------------- | --------------------------------------- |
| AVIF | Only 8-bit \* | Lossy |
| BMP | Yes | Rgb8, Rgba8, Gray8, GrayA8 |
| DDS | DXT1, DXT3, DXT5 | No |
| AVIF | Yes (8-bit only) \* | Yes (lossy only) |
| BMP | Yes | Yes |
| DDS | Yes | --- |
| Farbfeld | Yes | Yes |
| GIF | Yes | Yes |
| HDR | Yes | Yes |
| ICO | Yes | Yes |
| JPEG | Baseline and progressive | Baseline JPEG |
| OpenEXR | Rgb32F, Rgba32F (no dwa compression) | Rgb32F, Rgba32F (no dwa compression) |
| PNG | All supported color types | Same as decoding |
| PNM | PBM, PGM, PPM, standard PAM | Yes |
| JPEG | Yes | Yes |
| EXR | Yes | Yes |
| PNG | Yes | Yes |
| PNM | Yes | Yes |
| QOI | Yes | Yes |
| TGA | Yes | Rgb8, Rgba8, Bgr8, Bgra8, Gray8, GrayA8 |
| TIFF | Baseline(no fax support) + LZW + PackBits | Rgb8, Rgba8, Gray8 |
| WebP | Yes | Yes |
| TGA | Yes | Yes |
| TIFF | Yes | Yes |
| WebP | Yes | Yes (lossless only) |

- \* Requires the `avif-native` feature, uses the libdav1d C library.

### The [`ImageDecoder`](https://docs.rs/image/*/image/trait.ImageDecoder.html) and [`ImageDecoderRect`](https://docs.rs/image/*/image/trait.ImageDecoderRect.html) Traits
## Image Types

This crate provides a number of different types for representing images.
Individual pixels within images are indexed with (0,0) at the top left corner.

### [`ImageBuffer`](https://docs.rs/image/*/image/struct.ImageBuffer.html)
An image parameterised by its Pixel type, represented by a width and height and
a vector of pixels. It provides direct access to its pixels and implements the
`GenericImageView` and `GenericImage` traits.

### [`DynamicImage`](https://docs.rs/image/*/image/enum.DynamicImage.html)
A `DynamicImage` is an enumeration over all supported `ImageBuffer<P>` types.
Its exact image type is determined at runtime. It is the type returned when
opening an image. For convenience `DynamicImage` reimplements all image
processing functions.

### The [`GenericImageView`](https://docs.rs/image/*/image/trait.GenericImageView.html) and [`GenericImage`](https://docs.rs/image/*/image/trait.GenericImage.html) Traits

Traits that provide methods for inspecting (`GenericImageView`) and manipulating (`GenericImage`) images, parameterised over the image's pixel type.

### [`SubImage`](https://docs.rs/image/*/image/struct.SubImage.html)
A view into another image, delimited by the coordinates of a rectangle.
The coordinates given set the position of the top left corner of the rectangle.
This is used to perform image processing functions on a subregion of an image.


## The [`ImageDecoder`](https://docs.rs/image/*/image/trait.ImageDecoder.html) and [`ImageDecoderRect`](https://docs.rs/image/*/image/trait.ImageDecoderRect.html) Traits

All image format decoders implement the `ImageDecoder` trait which provide
basic methods for getting image metadata and decoding images. Some formats
Expand All @@ -62,81 +110,6 @@ The most important methods for decoders are...

All pixels are parameterised by their component type.

## Images
Individual pixels within images are indexed with (0,0) at the top left corner.
### The [`GenericImageView`](https://docs.rs/image/*/image/trait.GenericImageView.html) and [`GenericImage`](https://docs.rs/image/*/image/trait.GenericImage.html) Traits

Traits that provide methods for inspecting (`GenericImageView`) and manipulating (`GenericImage`) images, parameterised over the image's pixel type.

Some of these methods for `GenericImageView` are...
+ **dimensions**: Return a tuple containing the width and height of the image.
+ **get_pixel**: Returns the pixel located at (x, y).
+ **pixels**: Returns an Iterator over the pixels of this image.

While some of the methods for `GenericImage` are...
+ **put_pixel**: Put a pixel at location (x, y).
+ **copy_from**: Copies all of the pixels from another image into this image.

### Representation of Images
`image` provides two main ways of representing image data:

#### [`ImageBuffer`](https://docs.rs/image/*/image/struct.ImageBuffer.html)
An image parameterised by its Pixel types, represented by a width and height and a vector of pixels. It provides direct access to its pixels and implements the `GenericImageView` and `GenericImage` traits.

```rust
use image::{GenericImage, GenericImageView, ImageBuffer, RgbImage};

// Construct a new RGB ImageBuffer with the specified width and height.
let img: RgbImage = ImageBuffer::new(512, 512);

// Construct a new by repeated calls to the supplied closure.
let mut img = ImageBuffer::from_fn(512, 512, |x, y| {
if x % 2 == 0 {
image::Luma([0u8])
} else {
image::Luma([255u8])
}
});

// Obtain the image's width and height.
let (width, height) = img.dimensions();

// Access the pixel at coordinate (100, 100).
let pixel = img[(100, 100)];

// Or use the `get_pixel` method from the `GenericImage` trait.
let pixel = *img.get_pixel(100, 100);

// Put a pixel at coordinate (100, 100).
img.put_pixel(100, 100, pixel);

// Iterate over all pixels in the image.
for pixel in img.pixels() {
// Do something with pixel.
}
```

#### [`DynamicImage`](https://docs.rs/image/*/image/enum.DynamicImage.html)
A `DynamicImage` is an enumeration over all supported `ImageBuffer<P>` types.
Its exact image type is determined at runtime. It is the type returned when opening an image.
For convenience `DynamicImage` reimplements all image processing functions.

`DynamicImage` implement the `GenericImageView` and `GenericImage` traits for RGBA pixels.

#### [`SubImage`](https://docs.rs/image/*/image/struct.SubImage.html)
A view into another image, delimited by the coordinates of a rectangle.
The coordinates given set the position of the top left corner of the rectangle.
This is used to perform image processing functions on a subregion of an image.

```rust
use image::{GenericImageView, ImageBuffer, RgbImage, imageops};

let mut img: RgbImage = ImageBuffer::new(512, 512);
let subimg = imageops::crop(&mut img, 0, 0, 100, 100);

assert!(subimg.dimensions() == (100, 100));
```

## Image Processing Functions
These are the functions defined in the `imageops` module. All functions operate on types that implement the `GenericImage` trait.
Note that some of the functions are very slow in debug mode. Make sure to use release mode if you experience any performance issues.
Expand Down
36 changes: 19 additions & 17 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -205,23 +205,25 @@ pub mod flat;
///
/// <!--- NOTE: Make sure to keep this table in sync with the README -->
///
/// | Format | Decoding | Encoding |
/// | -------- | ----------------------------------------- | --------------------------------------- |
/// | AVIF | Only 8-bit | Lossy |
/// | BMP | Yes | Rgb8, Rgba8, Gray8, GrayA8 |
/// | DDS | DXT1, DXT3, DXT5 | No |
/// | Farbfeld | Yes | Yes |
/// | GIF | Yes | Yes |
/// | HDR | Yes | Yes |
/// | ICO | Yes | Yes |
/// | JPEG | Baseline and progressive | Baseline JPEG |
/// | OpenEXR | Rgb32F, Rgba32F (no dwa compression) | Rgb32F, Rgba32F (no dwa compression) |
/// | PNG | All supported color types | Same as decoding |
/// | PNM | PBM, PGM, PPM, standard PAM | Yes |
/// | QOI | Yes | Yes |
/// | TGA | Yes | Rgb8, Rgba8, Bgr8, Bgra8, Gray8, GrayA8 |
/// | TIFF | Baseline(no fax support) + LZW + PackBits | Rgb8, Rgba8, Gray8 |
/// | WebP | Yes | Yes |
// | Format | Decoding | Encoding |
// | -------- | ----------------------------------------- | --------------------------------------- |
// | AVIF | Yes (8-bit only) \* | Yes (lossy only) |
// | BMP | Yes | Yes |
// | DDS | Yes | --- |
// | Farbfeld | Yes | Yes |
// | GIF | Yes | Yes |
// | HDR | Yes | Yes |
// | ICO | Yes | Yes |
// | JPEG | Yes | Yes |
// | EXR | Yes | Yes |
// | PNG | Yes | Yes |
// | PNM | Yes | Yes |
// | QOI | Yes | Yes |
// | TGA | Yes | Yes |
// | TIFF | Yes | Yes |
// | WebP | Yes | Yes (lossless only) |
///
/// - \* Requires the `avif-native` feature, uses the libdav1d C library.
///
/// ## A note on format specific features
///
Expand Down

0 comments on commit bfc509e

Please sign in to comment.