Merge pull request #92 from johannesvollmer/api-rework

The new API (finally)

Author: johannesvollmer

Cargo.lock

@@ -4,7 +4,7 @@ description = "Read and write OpenEXR files without any unsafe code"
 keywords = ["exr", "openexr", "file", "binary", "io"]
 categories = ["encoding", "filesystem", "graphics", "multimedia"]
 
-version = "0.9.0"
+version = "1.0.0"
 edition = "2018"
 authors = ["johannesvollmer <[email protected]>"]
 

Cargo.toml

@@ -1,13 +1,13 @@
 [![Rust Docs](https://docs.rs/exr/badge.svg)](https://docs.rs/exr) 
 [![Crate Crate](https://img.shields.io/crates/v/exr.svg)](https://crates.io/crates/exr) 
-[![Rust Lang Version](https://img.shields.io/badge/rustc-1.43+-lightgray.svg)](https://blog.rust-lang.org/2020/04/23/Rust-1.43.0.html) 
+[![Rust Lang Version](https://img.shields.io/badge/rustc-1.48+-lightgray.svg)](https://blog.rust-lang.org/2020/11/19/Rust-1.48.html) 
 [![Lines of Code](https://tokei.rs/b1/github/johannesvollmer/exrs?category=code)](https://tokei.rs)
 
 # EXRS
 
 This library is a 100% Rust and 100% safe code library for
 reading and writing OpenEXR images.
-See [the examples](https://docs.rs/crate/exr/0.9.0/source/examples/) for a first impression.
+See [the examples](https://docs.rs/crate/exr/1.0.0/source/examples/) for a first impression.
 
 [OpenEXR](http://www.openexr.com/)
 is the de-facto standard image format in animation, VFX, and 
@@ -157,38 +157,34 @@ please leave an issue on this repository, containing the image file.
 Add this to your `Cargo.toml`:
 ```toml
 [dependencies]
-exr = "0.9.0"
+exr = "1.0.0"
 
 # also, optionally add this to your crate for smaller binary size 
 # and better runtime performance
 [profile.release]
 lto = true
 ```
 
-The master branch of this repository is always an up-to-date version.
+The master branch of this repository is always an up-to-date version, 
+so you could also link the github repository master branch.
 
 ### Example
 
-Example: [Write a generated RGB exr file](https://github.com/johannesvollmer/exrs/blob/master/examples/1_minimal_rgb.rs).
+Example: [generate an rgb exr file](https://github.com/johannesvollmer/exrs/blob/master/examples/1_minimal_rgb.rs).
 
 ```rust
 extern crate exr;
-use exr::prelude::rgba_image::*;
 
 fn main() {
-    // generate an image with 2048*2048 pixels, converting all numbers to f16
-    ImageInfo::rgb((2048, 2048), SampleType::F16).write_pixels_to_file(
-        "tests/images/out/minimal_rgba.exr",
-        write_options::high(), // higher speed, but higher memory usage
-
-        // generate a color for each pixel position
-        &|position: Vec2<usize>| {
-            Pixel::rgb(
-                position.x() as f32 / 2048.0, // red
-                position.y() as f32 / 2048.0, // green
-                1.0 - (position.y() as f32 / 2048.0), // blue
-            )
-        }
+    // write a file without alpha and 32-bit float precision per channel
+    exr::prelude::write_rgb_f32_file(
+        "tests/images/out/minimal_rgb.exr",
+        (2048, 2048), // write an image with 2048x2048 pixels
+        |x,y| ( // generate an f32 rgb color for each of the 2048x2048 pixels
+            x as f32 / 2048.0, // red
+            y as f32 / 2048.0, // green
+            1.0 - (y as f32 / 2048.0), // blue
+        )
     ).unwrap();
 }
 ```

README.md

@@ -0,0 +1,27 @@
+extern crate exr;
+
+/// `exr` offers a few very simple functions for the most basic use cases.
+/// `read_first_rgba_layer_from_file` is a simple function which loads an exr file.
+/// To load the image, you need to specify how to create and how to update your image.
+fn main() {
+    let image = exr::prelude::read_first_rgba_layer_from_file(
+        "tests/images/out/generated_rgba.exr", // run the `1_generate_rgba` example to generate this file
+
+        // instantiate your image type with the size of the image file
+        |info| {
+            let default_pixel = [0.0, 0.0, 0.0, 0.0];
+            let empty_line =  vec![ default_pixel; info.resolution.width() ];
+            let empty_image =  vec![ empty_line; info.resolution.height() ];
+            empty_image
+        },
+
+        // transfer the colors from the file to your image type
+        |pixel_vector, position, pixel| {
+            pixel_vector[position.y()][position.x()] = pixel.into()
+        },
+
+    ).unwrap();
+
+    // printing all pixels might kill the console lol, so only print some meta data about the image
+    println!("opened file generated_rgba.exr.exr: {:#?}", image.layer_data.attributes);
+}

examples/0_minimal_rgb_read.rs

@@ -0,0 +1,20 @@
+extern crate exr;
+
+/// `exr` offers a few very simple functions for the most basic use cases.
+/// `write_rgb_f32_file` is a simple function which writes a simple exr file.
+/// To write the image, you need to specify how to retrieve a single pixel from it.
+/// The closure may capture variables or generate data on the fly.
+fn main() {
+    // write a file without alpha and 32-bit float precision per channel
+    exr::prelude::write_rgb_f32_file(
+        "tests/images/out/minimal_rgb.exr",
+        (2048, 2048), // write an image with 2048x2048 pixels
+        |x,y| ( // generate an f32 rgb color for each of the 2048x2048 pixels
+            x as f32 / 2048.0, // red
+            y as f32 / 2048.0, // green
+            1.0 - (y as f32 / 2048.0), // blue
+        )
+    ).unwrap();
+
+    println!("created file minimal_rgb.exr");
+}

examples/0_minimal_rgb_write.rs

@@ -2,14 +2,14 @@
 
 // exr imports
 extern crate exr;
-use exr::prelude::common::*;
+use exr::prelude::*;
 
 /// Print the custom meta data of a file, excluding technical encoding meta data.
-/// Prints compression method and tile size, but not chunk count.
+/// Prints compression method and tile size, but not purely technical data like chunk count.
 fn main() {
     let meta_data = MetaData::read_from_file(
         "tests/images/valid/custom/crowskull/crow_uncompressed.exr",
-        true // do not throw an error for invalid attributes, skipping them instead
+        false // do not throw an error for invalid or missing attributes, skipping them instead
     ).unwrap();
 
     for (layer_index, image_layer) in meta_data.headers.iter().enumerate() {

examples/0_read_meta.rs

@@ -1,9 +1,9 @@
 
 // exr imports
 extern crate exr;
-use exr::prelude::rgba_image::*;
+use exr::prelude::*;
 
-/// Write an RGBA exr file, generating the pixel values on the fly.
+/// Write an rgba exr file, generating the pixel values on the fly.
 /// This streams the generated pixel directly to the file,
 /// never allocating the actual total pixel memory of the image.
 fn main() {
@@ -20,34 +20,39 @@ fn main() {
             value.powf((position.y() as f32 / scale.y()).sin() * 0.5 + 0.5)
         }
 
-        Pixel::rgb(
+        // return an rgba quadruple
+        (
             get_sample_f32(position, 0),
             get_sample_f32(position, 1),
             get_sample_f32(position, 2),
+            0.8
         )
     };
 
+    let mut attributes = LayerAttributes::named("generated rgba");
+    attributes.comments = Some(Text::from("This image was generated as part of an example"));
+    attributes.owner = Some(Text::from("The holy lambda function"));
 
-    let mut image_info = ImageInfo::rgb(
+    let layer = Layer::new(
         (2*2048, 2*2048),
+        attributes,
+        Encoding::SMALL_FAST_LOSSY,
 
-        // all generated f32 values are converted to an f16 while writing the file
-        SampleType::F16,
+        RgbaChannels::new(
+            // all generated f32 values are converted to an f16 while writing the file
+            RgbaSampleTypes::RGBA_F16,
+            generate_pixels
+        )
     );
 
-    image_info.layer_attributes.owner = Some("Unknown Owner".try_into().unwrap());
-    image_info.layer_attributes.comments = Some(
-        "This image was generated as part of an example".try_into().unwrap()
-    );
+    // crop away black and transparent pixels from the border
+    let layer = layer
+        .crop_where_eq((0.0, 0.0, 0.0, 0.0))
+        .or_crop_to_1x1_if_empty();
 
-    // write it to a file with all cores in parallel
-    image_info
-        .with_encoding(Encoding::for_compression(Compression::PIZ))
-        .write_pixels_to_file(
-            "tests/images/out/generated_rgba.exr",
-            write_options::high(), // this will actually generate the pixels in parallel on all cores
-            &generate_pixels
-        ).unwrap();
+    let image = Image::from_single_layer(layer);
 
+    // write it to a file with all cores in parallel
+    image.write().to_file("tests/images/out/generated_rgba.exr").unwrap();
     println!("created file generated_rgba.exr");
 }

examples/1_generate_rgba.rs

@@ -3,37 +3,44 @@ extern crate image as png;
 
 // exr imports
 extern crate exr;
-use exr::prelude::rgba_image as rgb_exr;
+use exr::prelude::*;
+use exr::prelude as exrs;
 
 fn main() {
 
-    // read the image from a file and keep only the png buffer
-    let (_info, png_buffer) = rgb_exr::ImageInfo::read_pixels_from_file(
-        "tests/images/valid/openexr/MultiResolution/Kapaa.exr",
-        rgb_exr::read_options::high(),
-
-        // how to create an empty png buffer from exr image meta data (used for loading the exr image)
-        |info: &rgb_exr::ImageInfo| -> png::RgbaImage {
-            png::ImageBuffer::new(
-                info.resolution.width() as u32,
-                info.resolution.height() as u32
-            )
-        },
-
-        // set each pixel in the png buffer from the exr file
-        |png_pixels: &mut png::RgbaImage, position: rgb_exr::Vec2<usize>, pixel: rgb_exr::Pixel| {
-            png_pixels.put_pixel(
-                position.x() as u32, position.y() as u32,
-
-                png::Rgba([
-                    tone_map(pixel.red.to_f32()),
-                    tone_map(pixel.green.to_f32()),
-                    tone_map(pixel.blue.to_f32()),
-                    (pixel.alpha_or_default().to_f32() * 255.0) as u8,
-                ])
-            );
-        },
-    ).unwrap();
+    // read from the exr file directly into a new `png::RgbaImage` image without intermediate buffers
+    let reader = exrs::read()
+        .no_deep_data()
+        .largest_resolution_level()
+        .rgba_channels(
+        |layer_info: &exrs::RgbaChannelsInfo| -> png::RgbaImage {
+                png::ImageBuffer::new(
+                    layer_info.resolution.width() as u32,
+                    layer_info.resolution.height() as u32
+                )
+            },
+
+            // set each pixel in the png buffer from the exr file
+            |png_pixels: &mut png::RgbaImage, position: exrs::Vec2<usize>, pixel: exrs::RgbaPixel| {
+                png_pixels.put_pixel(
+                    position.x() as u32, position.y() as u32,
+
+                    png::Rgba([
+                        tone_map(pixel.red.to_f32()),
+                        tone_map(pixel.green.to_f32()),
+                        tone_map(pixel.blue.to_f32()),
+                        (pixel.alpha_or_default().to_f32() * 255.0) as u8,
+                    ])
+                );
+            }
+        )
+        .first_valid_layer()
+        .all_attributes();
+
+    // an image that contains a single layer containing an png rgba buffer
+    let image: Image<Layer<RgbaChannels<png::RgbaImage>>> = reader
+        .from_file("tests/images/valid/openexr/MultiResolution/Kapaa.exr")
+        .unwrap();
 
 
     /// compress any possible f32 into the range of [0,1].
@@ -45,6 +52,7 @@ fn main() {
     };
 
     // save the png buffer to a png file
+    let png_buffer = &image.layer_data.channel_data.storage;
     png_buffer.save("tests/images/out/rgb.png").unwrap();
     println!("created image rgb.png")
 }