How do I use read_scanline from the piston image crate?

Question

I just started learning Rust and I really like to learn by building something 'real'. So I read through the Book, installed Rust, played around with the language and got cargo run working.

I then decided to try and read an image from disk and convert that image into a Vec. In this case, I want to detect the color of the pixels and store that somehow.

I broke it into multiple parts to learn Rust and its syntax:

Starting with:

1. Read an image from disk
2. Get the pixels of an image
3. Show colour code

This led me to the following code using the image crate:

extern crate image;

use std::path::Path;
use image::GenericImage;

fn main() {

    let img = image::open(&Path::new("src/maze.gif")).unwrap();

    let pixels = img.pixels();

    for e in pixels {
        let (_, _, color) = e;

        println!("Pixel colour {:?}", color);
    }

    println!("Dimensions {:?}", img.dimensions());
}

So proud as I am, I see some information popping up:

* snip *
Pixel colour Rgba { data: [255, 255, 255, 255] }
Pixel colour Rgba { data: [0, 0, 0, 255] }
Pixel colour Rgba { data: [255, 255, 255, 255] }
* snip *

Now I want to store for each line of the image its pixel information. I would like to have a Vec (is that correct?) with the info. A PHP array would look like this:

$a = [
   0 => [ Color, Color, Color, Color],
   1 => [ Color, Color, Color, Color]
];

Therefore my assumption is to use read_scanline. This is where reading AND understanding the documentation fails me completely.

What I think I need to do is:

1. Get the decoder for the current opened image
2. Call read_scanline on that decoder
3. Iterate over the results

But how?!

The code reads this:

read_scanline(&mut self, buf: &mut [u8]) -> ImageResult<u32>

I break this down as follows:

• First argument, an ImageDecoder object.
• Second argument a mutable 8 bit value.
• It returns an ImageResult object.

So I tried adapting the code slightly:

extern crate image;

use std::path::Path;
use image::GenericImage;
use image::ImageDecoder;

fn main() {

    let img = image::open(&Path::new("src/maze.gif")).unwrap();

    let pixels = img.pixels();
    let something: &mut [u8];
    let result = image::ImageDecoder::read_scanline(img, something);

    for e in pixels {
        let (_, _, color) = e;

        println!("Pixel colour {:?}", color);
    }

    println!("Dimensions {:?}", img.dimensions());
}

Which, as you might have guessed fails miserably.

error: mismatched types:
 expected `&mut _`,
    found `image::dynimage::DynamicImage`
(expected &-ptr,
    found enum `image::dynimage::DynamicImage`) [E0308]
src/main.rs:13     let result = image::ImageDecoder::read_scanline(img, something);

Obviously this is due to the fact I didn't pass an ImageDecoder object. But how can I? How should I read and understand the documentation. I think it is due to not understanding &mut self. I also do not understand how I should initiate this.

I hope someone can explain what it is I am missing and point me into the right direction.

Answer 1

Note I'm having trouble actually opening a GIF as each line says it is 0 bytes, so there's the possibility I've missed something important... I'll use a JPEG to demonstrate instead.

ImageDecoder is a trait. You need to use a concrete implementation of the trait. The documentation lists all known implementors of the trait, one of which is image::gif::Decoder, another is image::jpeg::JPEGDecoder.

read_scanline accepts a mutable self, which means that you normally will call it with method syntax: object.method(arg1). The first non-self argument is a mutable slice of bytes. The documentation states:

Reads one row from the image into buf and returns the row index

So the pixel data will be stored in the buffer. The next trick is to figure out how many bytes we need for a row and how many rows there are. ImageDecoder::row_len and ImageDecoder::dimensions address that respectively. Put together, we get something like this:

extern crate image;

use std::fs::File;

use image::jpeg;
use image::{GenericImage, ImageDecoder};
use image::{ColorType, Rgb, Pixel};

fn main() {
    let f = File::open("/tmp/cat.jpg").unwrap();
    let mut decoder = jpeg::JPEGDecoder::new(f);

    let (width, height) = decoder.dimensions().unwrap();
    let row_len = decoder.row_len().unwrap();

    println!("{} x {}, {}", width, height, row_len);

    let rows: Vec<_> = (0..height).map(|_| {
        let mut row = vec![0; row_len];
        decoder.read_scanline(&mut row).unwrap();
        row
    }).collect();
}

This loads the JPEG, row-by-row, into a Vec<Vec<u8>> - a vector of vectors of bytes.

To convert the raw data into pixels, we can use Pixel::from_slice, another trait method. In this case, I only handle one type of pixel - 8-bit RGB:

let colortype = decoder.colortype().unwrap();
assert_eq!(colortype, ColorType::RGB(8)); // Others are left to you!

let row_colors: Vec<Vec<_>> = rows.iter().map(|r| {
    r.chunks(3).map(|p| Rgb::from_slice(p)).collect()
}).collect();

I'm not in love with this because of the hard-coded 3. There should be some way of knowing that this pixel type only takes 3 bytes, but I'm not seeing anything obvious.