A Rust implementation of the greenfield image format
The greenfield image format is a simple 2D array of colors, prefixed with the width and height of the image, and a quantization information. All of the field are stored in big endian format.
- The first 64 bits(a full u64) are the greenfield magic value, used to identify
the file as a greenfield image (
b"grnfld42"). - The next 16 bits (a full u64) bits are the width of the image.
- The next 16 bits (a full u64) bits are the height of the image.
- The next 12 bits are the quantization information tuple (see
[
quantization]). A qunatization tuple is in the form:(bits_r, bits_g, bits_b), where each value is the number of bits used to store the respective color component. - The remaining bits are the image color data, in row-major order. Each color
has (bits_r + bits_g + bits_b) bits. So, for example, if the quantization
tuple is
(5, 6, 5), then each color is 16 bits. To get all the colors, you must read (width height) (bits_r + bits_g + bits_b) bits.
╔════════════════════════════╤══════════════════════════════════════════════════════════╗
║ Bits │ Description ║
╠════════════════════════════╪══════════════════════════════════════════════════════════╣
║ 64 │ b"grnfld42": Magic value (0x47524E464C443432) ║
╟────────────────────────────┼──────────────────────────────────────────────────────────╢
║ 16 │ u32: Image width ║
╟────────────────────────────┼──────────────────────────────────────────────────────────╢
║ 16 │ u32: Image height ║
╟────────────────────────────┼──────────────────────────────────────────────────────────╢
║ 12 │ (bits_r, bits_g, bits_b): Quantization tuple ║
╟────────────────────────────┼──────────────────────────────────────────────────────────╢
║ width * height * │ [RGB]: (bits_r + bits_g + bits_r) per pixel ║
║ (bits_r + bits_g + bits_b) │ row-major ║
╚════════════════════════════╧══════════════════════════════════════════════════════════╝
Rgb quantization is the process of reducing the color space size of an image with the objective of reducing the size of the image in disk. This is done by grouping similar colors in the space and referring to the group instead of a particular color.
Greenfield images uses a quantization technique know as Uniform Quantization. In uniform quantization, we divide each component of the color space in equal intervals, indexing each interval with a number, and then we assign a color to each interval (usually the mean of this interval), in the end, we just store on disk this index, instead of the color. With that, we can reduce the number of bits needed to store each component of a color. Once an image has been loaded from disk, we can find the respective color for each index (the mean of an interval represented by that index) and reconstruct the image.
For example, if we have a 24-bit RGB image, we can reduce the number of bits needed to store each component to 5 bits, reducing the number of bits needed to store each pixel from 24 to 15. Reducing each component to 5 bits, we now have 2^5 = 32 possible values for each component. Each distinct value is the mean of the interval in the RGB color space.
This library is available on crates.io/crates/greenfield. So, just install it with cargo:
cargo add greenfielduse std::error::Error;
use greenfield::prelude::*;
fn main() -> Result<(), Box<dyn Error>> {
// Creation of images
let image = Image::new(
1,
1,
UniformQuantization::new(5, 6, 5)?,
vec![Rgb::new(255, 255, 255)],
)?;
println!("Image: {}", image);
// Fields
let (width, height) = image.dimensions();
let quantization = image.quantization();
println!("Dimensions: {}x{}", width, height);
println!("Quantization: {}", quantization);
// Iterators over image data
let colors = image.colors().collect::<Vec<&Rgb>>(); // Vec<Item = Rgb>
let pixels = image.pixels(); // Iter<Item = Pixel>
let bytes = image.bytes(); // Iter<Item = u8>
for color in colors {
println!("Color: {}", color);
}
for pixel in pixels {
println!("Pixel: {}", pixel);
}
for byte in bytes {
println!("Byte: {}", byte);
}
Ok(())
}Lenna image quantized to 5 6 5 bits.
This crate use the deku for serialization and deserialization operations.
I've provided some utility methods on top of that for conversions between greenfield images and bytes:
use std::{error::Error, path::PathBuf};
use greenfield::prelude::*;
fn main() -> Result<(), Box<dyn Error>> {
let image = Image::new(
1,
1,
UniformQuantization::new(8, 8, 8)?,
vec![Rgb::new(255, 255, 255)],
)?;
// to/from bytes
let serialized = image.clone().serialize()?;
let deserialized = Image::deserialize(&serialized)?;
println!("{}", deserialized);
// to/from file
image.to_file(&PathBuf::from("image.gfd"))?;
let img = Image::from_file(&PathBuf::from("image.gfd"))?;
println!("{}", img);
Ok(())
}For conversion between gfd files and other formats (e.g. png and bmp) the crate image is used.
I have provided the functions greenfield::io::{load_image, and save_image} for
simplicity sake. Note that the formats used for saving or loading are inferred
from filename extensions (e.g. .png saves as png and.gfd as greenfield).
use std::{error::Error, path::PathBuf};
use greenfield::prelude::*;
fn main() -> Result<(), Box<dyn Error>> {
// Load a PNG an save as GFD
let lenna = load_image(
&PathBuf::from("Lenna.png"),
UniformQuantization::new(8, 8, 8)?,
)?;
save_image(&lenna, &PathBuf::from("Lenna.gfd"))?;
// Load a GFD and save as PNG
let lenna_gfd = load_image(
&PathBuf::from("Lenna.gfd"),
UniformQuantization::new(8, 8, 8)?,
)?;
save_image(&lenna_gfd, &PathBuf::from("Lenna.png"))?;
Ok(())
}