Tiff Writer

https://docs.rs/tiff-writer/0.2.5/tiff_writer
Admin
A library for building, compressing, encoding, and writing TIFF images, providing modules for image...
Tokens:30,251
Snippets:296
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Getting references to Result contents with `as_ref()`

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

The `as_ref()` method converts a `&Result<T, E>` into a `Result<&T, &E>`, providing references to the contained values without consuming the original `Result`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Get Block Sample Count

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Returns the expected number of samples for a specific block (strip or tile) at the given index.

```rust
pub fn block_sample_count(&self, index: usize) -> usize
```

--------------------------------

### Get Estimated Uncompressed Bytes

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Calculates and returns the estimated total size of the uncompressed image data in bytes.

```rust
pub fn estimated_uncompressed_bytes(&self) -> u64
```

--------------------------------

### Get Total Block Count

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Returns the total number of blocks (strips or tiles) configured for this image.

```rust
pub fn block_count(&self) -> usize
```

--------------------------------

### Getting mutable references to Result contents with `as_mut()`

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

The `as_mut()` method converts a `&mut Result<T, E>` into a `Result<&mut T, &mut E>`, providing mutable references to the contained values.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Configure Sample Format from Type

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Configures bits_per_sample and sample_format based on a provided TiffWriteSample type. This simplifies setting up common data types.

```rust
pub fn sample_type<T: TiffWriteSample>(self) -> Self
```

--------------------------------

### Configure Sample Format

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Sets the data format for samples, such as unsigned integer, signed integer, or floating-point.

```rust
pub fn sample_format(self, fmt: SampleFormat) -> Self
```

--------------------------------

### Get Block Samples Per Pixel

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Returns the number of samples per pixel that are represented within a single block.

```rust
pub fn block_samples_per_pixel(&self) -> u16
```

--------------------------------

### Basic TIFF Image Creation and Writing

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/index.html

Demonstrates how to create a new TIFF writer, add an image with specified dimensions and sample type, write image data, and finalize the TIFF file. This snippet is useful for basic image encoding tasks.

```rust
use tiff_writer::{TiffWriter, WriteOptions, ImageBuilder};
use tiff_core::Compression;
use std::io::Cursor;

let mut buf = Cursor::new(Vec::new());
let mut writer = TiffWriter::new(&mut buf, WriteOptions::default()).unwrap();

let image = ImageBuilder::new(4, 4).sample_type::<u8>();
let handle = writer.add_image(image).unwrap();
writer.write_block(&handle, 0, &[0u8; 16]).unwrap();
writer.finish().unwrap();

```

--------------------------------

### Configure Tile-Based Layout

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Configures the image to use tile-based storage, specifying the width and height of each tile.

```rust
pub fn tiles(self, tile_width: u32, tile_height: u32) -> Self
```

--------------------------------

### Create New ImageBuilder

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Initializes a new ImageBuilder with the essential width and height parameters for an image.

```rust
pub fn new(width: u32, height: u32) -> Self
```

--------------------------------

### Get Block Row Width

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Returns the width in pixels of a row within a block (strip or tile). This is either the tile width or the image width.

```rust
pub fn block_row_width(&self) -> usize
```

--------------------------------

### Configure Compression

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Sets the compression method for the image data. Supported compressions include None, PackBits, LZW, and Deflate.

```rust
pub fn compression(self, c: Compression) -> Self
```

--------------------------------

### Get Offset and Bytecount Tag Codes

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Returns the TIFF tag codes used for the offset and bytecount arrays, which are crucial for locating image data.

```rust
pub fn offset_tag_codes(&self) -> (u16, u16)
```

--------------------------------

### Default Implementation for WriteOptions

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.WriteOptions.html

Provides a default configuration for WriteOptions. Useful when a standard set of options is required without specific customization.

```rust
fn default() -> Self
```

--------------------------------

### Collecting Results from an Iterator

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Use `collect()` on an iterator of Results to gather all Ok values into a container or return the first Err encountered. This example demonstrates checking for integer overflow.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| 
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

--------------------------------

### into_ok

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained Ok value, but never panics. This is an experimental API.

```APIDOC
## into_ok

### Description
Returns the contained `Ok` value, but never panics. Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Method
`into_ok()`

### Parameters
None

### Request Example
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

### Response
#### Success Response
- `T`: The contained `Ok` value.

#### Response Example
```rust
// If Ok("this is fine"), returns "this is fine"
```
```

--------------------------------

### Recommended expect Message Style

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Provides guidance on crafting effective expect messages, focusing on the reason why the Result is expected to be Ok. This helps in debugging by providing clear context on failure.

```Rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### Calculating Sum of Iterator Results with Error Handling

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Use `sum()` on an iterator of `Result`s to compute the sum of all successful values. If any element is an `Err` or fails a condition (like being negative in this example), it short-circuits and returns that `Err`.

```rust
let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };
let v = vec![1, 2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Ok(3));
```

```rust
let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };
let v = vec![1, -2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Err("Negative element found"));
```

--------------------------------

### ImageBuilder::new

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Creates a new ImageBuilder with the specified width and height for the image.

```APIDOC
## ImageBuilder::new

### Description
Creates a new image builder with required dimensions.

### Method

```
pub fn new(width: u32, height: u32) -> Self
```

### Parameters

* **width** (u32) - Required - The width of the image.
* **height** (u32) - Required - The height of the image.
```

--------------------------------

### Clone Implementation for WriteOptions

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.WriteOptions.html

Provides methods to duplicate WriteOptions values. Ensures that writer configurations can be easily copied.

```rust
fn clone(&self) -> WriteOptions
```

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### Create a new TiffWriter

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.TiffWriter.html

Initializes a new TiffWriter. Writes the file header immediately. Supports automatic TIFF variant selection based on estimated image size.

```rust
pub fn new(sink: W, options: WriteOptions) -> Result<Self>
```

--------------------------------

### ImageBuilder Configuration Methods

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Methods for configuring various aspects of the image, such as samples per pixel, bits per sample, compression, and layout.

```APIDOC
## ImageBuilder Configuration Methods

### Description
These methods allow for detailed configuration of the image builder.

### Methods

* **samples_per_pixel(spp: u16)**: Sets the number of samples per pixel.
* **bits_per_sample(bps: u16)**: Sets the number of bits per sample.
* **sample_format(fmt: SampleFormat)**: Sets the sample format.
* **sample_type<T: TiffWriteSample>()**: Configures from a TiffWriteSample type, setting bits_per_sample and sample_format.
* **compression(c: Compression)**: Sets the compression method.
* **predictor(p: Predictor)**: Sets the predictor.
* **photometric(p: PhotometricInterpretation)**: Sets the photometric interpretation.
* **planar_configuration(p: PlanarConfiguration)**: Sets the planar configuration (chunky or separate planar).
* **strips(rows_per_strip: u32)**: Configures strip-based layout.
* **tiles(tile_width: u32, tile_height: u32)**: Configures tile-based layout.
* **tag(tag: Tag)**: Adds an arbitrary extra tag to the IFD.
* **overview()**: Marks this IFD as a reduced-resolution overview.
```

--------------------------------

### Configure Strip-Based Layout

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Configures the image to use strip-based storage, specifying the number of rows per strip.

```rust
pub fn strips(self, rows_per_strip: u32) -> Self
```

--------------------------------

### Mark as Overview Image

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Marks this IFD as a reduced-resolution overview image, typically used for thumbnail previews.

```rust
pub fn overview(self) -> Self
```

--------------------------------

### Configure Samples Per Pixel

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Sets the number of samples per pixel for the image. This is typically 1 for grayscale and 3 for RGB.

```rust
pub fn samples_per_pixel(self, spp: u16) -> Self
```

--------------------------------

### CloneToUninit Trait Implementation (Nightly)

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.ImageHandle.html

Provides an experimental, nightly-only method for cloning the ImageHandle into uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### unwrap_or

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained `Ok` value or a provided default. Arguments are eagerly evaluated.

```APIDOC
## unwrap_or

### Description
Returns the contained `Ok` value or a provided default. Arguments passed to `unwrap_or` are eagerly evaluated.

### Method
`unwrap_or`

### Parameters
- `default` (T) - The default value to return if `self` is `Err`.

### Request Example
```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

### Response
#### Success Response
- `T` - The contained `Ok` value or the provided default value.
```

--------------------------------

### Build Layout-Specific Tags

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Constructs and returns a vector of TIFF tags related to the image's layout, such as RowsPerStrip or TileWidth/TileLength.

```rust
pub fn layout_tags(&self) -> Vec<Tag>
```

--------------------------------

### Handling File Metadata Operations with Result

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Shows how to use `Result` to handle potential errors when accessing file metadata, such as checking modification times. It demonstrates checking for success and specific error kinds like `NotFound`.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Converting Result to Vec (Ok case)

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Demonstrates converting an `Ok` Result into an iterator and collecting its value into a vector.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);
```

--------------------------------

### TiffWriter::new

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.TiffWriter.html

Creates a new TIFF writer instance. It immediately writes the file header. The `TiffVariant::Auto` option initially uses classic TIFF and may switch to BigTIFF if image size exceeds 4 GiB.

```APIDOC
## TiffWriter::new

### Description
Create a new TIFF writer. Writes the file header immediately.
With `TiffVariant::Auto`, classic TIFF is used initially. If the cumulative estimated image size exceeds 4 GiB when `add_image` is called, the writer returns an error recommending `TiffVariant::BigTiff`. Use `WriteOptions::auto(estimated_bytes)` for automatic selection.

### Method
`pub fn new(sink: W, options: WriteOptions) -> Result<Self>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- `Self` (TiffWriter<W>) - A new TiffWriter instance.

#### Response Example
None
```

--------------------------------

### Configure Planar Configuration

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Sets the planar configuration for multi-band images, specifying whether samples are interleaved (chunky) or stored in separate planes.

```rust
pub fn planar_configuration(self, p: PlanarConfiguration) -> Self
```

--------------------------------

### Create Auto WriteOptions

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.WriteOptions.html

Generates WriteOptions that automatically select BigTIFF based on estimated total bytes. Useful for handling potentially large TIFF files.

```rust
pub fn auto(estimated_bytes: u64) -> Self
```

--------------------------------

### Unwrap Ok Value (Never Panics)

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained `Ok` value, but never panics. This is an experimental API.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Using or to Provide a Default Error Value

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Illustrates the `or` method, which returns the `Ok` value of the first `Result` if it's `Ok`, otherwise returns the second `Result`. This is useful for providing a fallback error value.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

--------------------------------

### pub fn unwrap(self) -> T

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`.

```APIDOC
## pub fn unwrap(self) -> T

### Description
Returns the contained `Ok` value, consuming the `self` value. Because this function may panic, its use is generally discouraged. Panics are meant for unrecoverable errors, and may abort the entire program.

### Method
(Implicitly called on a Result object)

### Parameters
None

### Response
* `T` - The contained Ok value.

### Panics
Panics if the value is an `Err`.

### Note
Instead, prefer to use the `?` (try) operator, or pattern matching to handle the `Err` case explicitly, or call `unwrap_or`, `unwrap_or_else`, or `unwrap_or_default`.
```

--------------------------------

### WriteOptions Struct Definition

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.WriteOptions.html

Defines the structure for writer configuration, including byte order and TIFF variant.

```rust
pub struct WriteOptions {
    pub byte_order: ByteOrder,
    pub variant: TiffVariant,
}
```

--------------------------------

### From and Into Trait Implementations

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.ImageHandle.html

Implements the From and Into traits, facilitating conversions to and from the ImageHandle type.

```rust
fn from(t: T) -> T
```

```rust
fn into(self) -> U
```

--------------------------------

### pub fn expect(self, msg: &str) -> T

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`.

```APIDOC
## pub fn expect(self, msg: &str) -> T

### Description
Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`, with a panic message including the passed message and the content of the `Err`.

### Method
(Implicitly called on a Result object)

### Parameters
* `msg`: &str - The message to include in the panic if the Result is an Err.

### Response
* `T` - The contained Ok value.

### Panics
Panics if the value is an `Err`.

### Request Example
```rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

### Recommended Message Style
We recommend that `expect` messages are used to describe the reason you _expect_ the `Result` should be `Ok`.
```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```
```

--------------------------------

### Combine Results (Eager Evaluation)

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the second `Result` if the first is `Ok`, otherwise returns the `Err` of the first. Arguments are eagerly evaluated.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

--------------------------------

### Configure Bits Per Sample

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Sets the number of bits per sample. Common values include 8, 16, or 32.

```rust
pub fn bits_per_sample(self, bps: u16) -> Self
```

--------------------------------

### pub fn as_deref_mut(&mut self) -> Result<&mut <T as Deref>::Target, &mut E>

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Converts from `Result<T, E>` to `Result<&mut <T as DerefMut>::Target, &mut E>` by coercing the `Ok` variant via `DerefMut`.

```APIDOC
## pub fn as_deref_mut(&mut self) -> Result<&mut <T as DerefMut>::Target, &mut E>

### Description
Converts from `Result<T, E>` (or `&mut Result<T, E>`) to `Result<&mut <T as DerefMut>::Target, &mut E>`. Coerces the `Ok` variant of the original `Result` via `DerefMut` and returns the new `Result`.

### Method
(Implicitly called on a mutable Result object)

### Parameters
None

### Response
* `Result<&mut <T as DerefMut>::Target, &mut E>` - A new Result with a mutable reference to the dereferenced Ok value or a mutable reference to the original Err value.

### Request Example
```rust
let mut s = "HELLO".to_string();
let mut x: Result<String, u32> = Ok("hello".to_string());
let y: Result<&mut str, &mut u32> = Ok(&mut s);
assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);

let mut i = 42;
let mut x: Result<String, u32> = Err(42);
let y: Result<&mut str, &mut u32> = Err(&mut i);
assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);
```
```

--------------------------------

### Converting Result to Option with `ok()`

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

The `ok()` method converts a `Result<T, E>` into an `Option<T>`. It consumes the `Result`, returning `Some(T)` if it was `Ok`, and `None` if it was `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

--------------------------------

### Clone Implementation for ImageHandle

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.ImageHandle.html

Provides methods for cloning an ImageHandle, allowing for duplicate values to be created. This is useful for managing multiple references to the same image identifier.

```rust
fn clone(&self) -> ImageHandle
```

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### build_image_tags

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/encoder/fn.build_image_tags.html

Builds standard TIFF tags for an image. For BigTIFF, offset/bytecount arrays use Long8 instead of Long.

```APIDOC
## build_image_tags

### Description
Builds standard TIFF tags for an image. For BigTIFF, offset/bytecount arrays use Long8 instead of Long.

### Function Signature
```rust
pub fn build_image_tags(p: &ImageTagParams<'_>) -> Vec<Tag>
```

### Parameters
#### Path Parameters
- **p** (*ImageTagParams*) - Required - A reference to ImageTagParams containing image details.
```

--------------------------------

### Write a pre-compressed data block

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.TiffWriter.html

Writes a block of data that has already been compressed. This bypasses the writer's internal compression pipeline.

```rust
pub fn write_block_raw( &mut self, handle: &ImageHandle, block_index: usize, compressed_bytes: &[u8], ) -> Result<()>
```

--------------------------------

### unwrap_or_default

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained Ok value or a default value if the Result is Err.

```APIDOC
## unwrap_or_default

### Description
Consumes the `self` argument then, if `Ok`, returns the contained value, otherwise if `Err`, returns the default value for that type.

### Method
`unwrap_or_default()`

### Parameters
None

### Request Example
```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

### Response
#### Success Response
- `T`: The contained `Ok` value or the default value for the type `T`.

#### Response Example
```rust
// If Ok(1909), returns 1909
// If Err, returns 0 (default for integers)
```
```

--------------------------------

### unwrap

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained Ok value. Panics if the value is an Err, with a panic message provided by the Err's value.

```APIDOC
## unwrap

### Description
Returns the contained `Ok` value. Panics if the value is an `Err`, with a panic message provided by the `Err`’s value.

### Method
`unwrap()`

### Parameters
None

### Request Example
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

### Response
#### Success Response
- `T`: The contained `Ok` value.

#### Response Example
```rust
// If Ok(2), returns 2
```

### Error Handling
Panics if the value is an `Err`.
```

--------------------------------

### compress

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/compress/fn.compress.html

Compresses raw bytes using the specified compression scheme and returns the compressed data.

```APIDOC
## compress

### Description
Compresses raw bytes using the specified compression scheme.

### Method
Rust Function

### Signature
```rust
pub fn compress(data: &[u8], compression: Compression, index: usize) -> Result<Vec<u8>>
```

### Parameters
#### Path Parameters
- **data** (&[u8]) - The raw byte slice to compress.
- **compression** (Compression) - The compression scheme to use.
- **index** (usize) - An index related to the compression process.

#### Return Value
- Result<Vec<u8>> - A Result containing the compressed byte vector on success, or an error on failure.
```

--------------------------------

### Chaining Fallible Operations with and_then

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Demonstrates chaining operations that can fail using `and_then`. This is useful for sequential computations where each step might produce an error.

```rust
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
    x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
}

assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

--------------------------------

### WriteOptions::auto

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.WriteOptions.html

Creates WriteOptions with automatic BigTIFF selection based on estimated total bytes. This is useful for ensuring compatibility with large TIFF files.

```APIDOC
## `WriteOptions::auto`

### Description
Creates options that auto-select BigTIFF based on estimated total bytes.

### Method
`pub fn auto(estimated_bytes: u64) -> Self`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- `Self` (WriteOptions) - The created WriteOptions instance.

### Response Example
None
```

--------------------------------

### or

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns `res` if the result is `Err`, otherwise returns the `Ok` value of `self`. Arguments are eagerly evaluated.

```APIDOC
## or

### Description
Returns `res` if the result is `Err`, otherwise returns the `Ok` value of `self`. Arguments passed to `or` are eagerly evaluated.

### Method
`or`

### Parameters
- `res` (Result<T, F>) - The result to return if `self` is `Err`.

### Request Example
```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));
```

### Response
#### Success Response
- `Result<T, F>` - Either the `Ok` value of `self` or the provided `res` if `self` was `Err`.
```

--------------------------------

### ImageBuilder::validate

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Validates the current image configuration.

```APIDOC
## ImageBuilder::validate

### Description
Validates the configuration of the image builder.

### Method

```
pub fn validate(&self) -> Result<()>
```

### Returns

* **Result<()**: Ok if the configuration is valid, Err otherwise.
```

--------------------------------

### ImageBuilder Information Methods

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Methods to retrieve information about the configured image, such as block counts, byte estimates, and tag codes.

```APIDOC
## ImageBuilder Information Methods

### Description
These methods provide information about the image configuration.

### Methods

* **block_count() -> usize**: Returns the total number of blocks (strips or tiles).
* **block_sample_count(index: usize) -> usize**: Returns the expected number of samples for a given block index.
* **estimated_uncompressed_bytes() -> u64**: Returns the estimated uncompressed image bytes.
* **offset_tag_codes() -> (u16, u16)**: Returns the TIFF tag codes for offset and bytecount arrays.
* **layout_tags() -> Vec<Tag>**: Returns the layout-specific tags.
* **block_row_width() -> usize**: Returns the row width in pixels for the compression pipeline.
* **block_samples_per_pixel() -> u16**: Returns the samples per pixel represented in a single block.
```

--------------------------------

### TryFrom and TryInto Trait Implementations

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.ImageHandle.html

Implements the TryFrom and TryInto traits, enabling fallible conversions to and from the ImageHandle type.

```rust
type Error = Infallible
```

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

```rust
type Error = <U as TryFrom<T>>::Error
```

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Copying Result<&mut T, E>

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Maps a `Result<&mut T, E>` to a `Result<T, E>` by copying the contents of the `Ok` part. Requires `T` to implement `Copy`.

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Unwrap Ok Value

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Unwraps the `Ok` value. Panics if the value is `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

--------------------------------

### pub fn as_deref(&self) -> Result<&<T as Deref>::Target, &E>

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Converts from `Result<T, E>` to `Result<&<T as Deref>::Target, &E>` by coercing the `Ok` variant via `Deref`.

```APIDOC
## pub fn as_deref(&self) -> Result<&<T as Deref>::Target, &E>

### Description
Converts from `Result<T, E>` (or `&Result<T, E>`) to `Result<&<T as Deref>::Target, &E>`. Coerces the `Ok` variant of the original `Result` via `Deref` and returns the new `Result`.

### Method
(Implicitly called on a Result object)

### Parameters
None

### Response
* `Result<&<T as Deref>::Target, &E>` - A new Result with a reference to the dereferenced Ok value or a reference to the original Err value.

### Request Example
```rust
let x: Result<String, u32> = Ok("hello".to_string());
let y: Result<&str, &u32> = Ok("hello");
assert_eq!(x.as_deref(), y);

let x: Result<String, u32> = Err(42);
let y: Result<&str, &u32> = Err(&42);
assert_eq!(x.as_deref(), y);
```
```

--------------------------------

### Debug Implementation for ImageHandle

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.ImageHandle.html

Enables the ImageHandle to be formatted for debugging purposes, allowing its state to be inspected.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

--------------------------------

### Any Trait Implementation

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.ImageHandle.html

Implements the Any trait, allowing for runtime type identification of the ImageHandle.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Configure Photometric Interpretation

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Sets the photometric interpretation of the image, defining how pixel values should be interpreted (e.g., grayscale, RGB, palette-based).

```rust
pub fn photometric(self, p: PhotometricInterpretation) -> Self
```

--------------------------------

### ok

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Converts a Result<T, E> into an Option<T>. If the Result is Ok(v), it returns Some(v). If the Result is Err(e), it returns None.

```APIDOC
## pub fn ok(self) -> Option<T>

### Description
Converts from `Result<T, E>` to `Option<T>`.
Consumes `self`, converting the error into `None` if present.

### Method
`ok()`

### Parameters
None

### Response
- `Option<T>`: `Some(T)` if the Result was `Ok`, `None` if the Result was `Err`.

### Request Example
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```
```

--------------------------------

### Cloning Result<&mut T, E>

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Maps a `Result<&mut T, E>` to a `Result<T, E>` by cloning the contents of the `Ok` part. Requires `T` to implement `Clone`.

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### write_ifd Function

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/encoder/fn.write_ifd.html

Writes an Image File Directory (IFD), either Classic or BigTIFF, to a given sink. The tags provided must be sorted by their code.

```APIDOC
## Function write_ifd

### Description
Writes an IFD (Classic or BigTIFF). Tags must be sorted by code.

### Signature
```rust
pub fn write_ifd<W: Write + Seek>(
    sink: &mut W,
    byte_order: ByteOrder,
    is_bigtiff: bool,
    tags: &[Tag],
    offsets_tag_code: u16,
    byte_counts_tag_code: u16,
    _num_blocks: usize,
) -> Result<IfdWriteResult>
```

### Parameters
* `sink`: A mutable reference to a type implementing `Write` and `Seek`, representing the output destination.
* `byte_order`: The `ByteOrder` to use for writing the IFD.
* `is_bigtiff`: A boolean indicating whether to write a BigTIFF IFD.
* `tags`: A slice of `Tag` structs, which must be sorted by their code.
* `offsets_tag_code`: The tag code to use for offsets.
* `byte_counts_tag_code`: The tag code to use for byte counts.
* `_num_blocks`: This parameter is unused in the current implementation.

### Returns
Returns a `Result<IfdWriteResult>` which is `Ok(IfdWriteResult)` on success or an `Err` containing a `tiff_writer::Error` on failure.
```

--------------------------------

### Unwrap or Default Value

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained `Ok` value or a default value if `Err`. Requires the error type to implement `Default`.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### Build Standard TIFF Tags

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/encoder/fn.build_image_tags.html

Use this function to generate standard TIFF tags for an image. For BigTIFF images, it correctly uses Long8 for offset and bytecount arrays.

```rust
pub fn build_image_tags(p: &ImageTagParams<'_>) -> Vec<Tag>
```

--------------------------------

### Enum DataLayout Definition

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/enum.DataLayout.html

Defines the two possible data layout strategies for TIFF images: Strips and Tiles. Use Strips for row-by-row organization and Tiles for block-based organization.

```rust
pub enum DataLayout {
    Strips {
        rows_per_strip: u32,
    },
    Tiles {
        width: u32,
        height: u32,
    },
}
```

--------------------------------

### Result::is_ok_and

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns `true` if the result is `Ok` and the contained value satisfies a given predicate.

```APIDOC
## Result::is_ok_and

### Description

Returns `true` if the result is `Ok` and the value inside of it matches a predicate. This allows for checking both the success state and a condition on the success value in one step.

### Method Signature

```rust
pub fn is_ok_and<F>(self, f: F) -> bool
where F: FnOnce(T) -> bool
```

### Examples

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```
```

--------------------------------

### map_or_default

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Maps a Result<T, E> to a U by applying a function to the Ok value, or returning the default value of U if the Result is Err. This is an experimental nightly-only API.

```APIDOC
## pub const fn map_or_default<U, F>(self, f: F) -> U
where F: FnOnce(T) -> U, U: Default

### Description
🔬This is a nightly-only experimental API. (`result_option_map_or_default`)
Maps a `Result<T, E>` to a `U` by applying function `f` to the contained value if the result is `Ok`, otherwise if `Err`, returns the default value for the type `U`.

### Method
`map_or_default(f)`

### Parameters
- `f` (FnOnce(T) -> U): A function that takes the `Ok` value and returns a value of type `U`.

### Response
- `U`: The result of the function `f` if the Result was `Ok`, or the default value of `U` if the Result was `Err`.

### Request Example
```rust
#![feature(result_option_map_or_default)]

let x: Result<_, &str> = Ok("foo");
let y: Result<&str, _> = Err("bar");

assert_eq!(x.map_or_default(|x| x.len()), 3);
assert_eq!(y.map_or_default(|y| y.len()), 0);
```
```

--------------------------------

### Unwrapping Result with expect (Panics on Err)

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained Ok value, consuming the Result. Panics if the value is an Err, with a message including the provided string and the error's content. Use with caution.

```Rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

--------------------------------

### Clone From ImageBuilder

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Performs copy-assignment from another ImageBuilder instance. This is an optimized way to duplicate the state.

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### compress_block

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/compress/fn.compress_block.html

The compress_block function takes raw samples and applies the full compression pipeline, including byte order conversion, predictor application, and compression, to produce a `Vec<u8>` representing the compressed block.

```APIDOC
## Function compress_block

### Description
Full compression pipeline: native samples → file-order bytes → predictor → compress.

### Signature
```rust
pub fn compress_block<T: TiffWriteSample>(
    samples: &[
        T
    ],
    byte_order: ByteOrder,
    compression: Compression,
    predictor: Predictor,
    samples_per_pixel: u16,
    row_width_pixels: usize,
    index: usize,
) -> Result<Vec<u8>>
```

### Parameters

*   **samples** (*&[T]*) - Required - A slice of samples of type T, where T implements `TiffWriteSample`.
*   **byte_order** (*ByteOrder*) - Required - The byte order to use for the file.
*   **compression** (*Compression*) - Required - The compression method to apply.
*   **predictor** (*Predictor*) - Required - The predictor to use before compression.
*   **samples_per_pixel** (*u16*) - Required - The number of samples per pixel.
*   **row_width_pixels** (*usize*) - Required - The width of a row in pixels.
*   **index** (*usize*) - Required - The index of the block.

### Returns

*   **Result<Vec<u8>>** - A `Result` containing a `Vec<u8>` of the compressed block on success, or an error on failure.
```

--------------------------------

### i64 Implementation for TiffWriteSample

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/sample/trait.TiffWriteSample.html

Implements the TiffWriteSample trait for the i64 type. Specifies that i64 samples have a format code of 2, 64 bits per sample, and 8 bytes per sample.

```rust
const SAMPLE_FORMAT: u16 = 2;
    const BITS_PER_SAMPLE: u16 = 64;
    const BYTES_PER_SAMPLE: usize = 8;

    fn encode_slice(samples: &[Self], byte_order: ByteOrder) -> Vec<u8>;

```

--------------------------------

### f64 Implementation for TiffWriteSample

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/sample/trait.TiffWriteSample.html

Implements the TiffWriteSample trait for the f64 type. Specifies that f64 samples have a format code of 3, 64 bits per sample, and 8 bytes per sample.

```rust
const SAMPLE_FORMAT: u16 = 3;
    const BITS_PER_SAMPLE: u16 = 64;
    const BYTES_PER_SAMPLE: usize = 8;

    fn encode_slice(samples: &[Self], byte_order: ByteOrder) -> Vec<u8>;

```

--------------------------------

### Write a single data block for an image

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/writer/struct.TiffWriter.html

Writes a single strip or tile for a given image. The data is processed through the compression pipeline.

```rust
pub fn write_block<T: TiffWriteSample>( &mut self, handle: &ImageHandle, block_index: usize, samples: &[T], ) -> Result<()>
```

--------------------------------

### ImageTagParams Struct Definition

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/encoder/struct.ImageTagParams.html

Defines the structure for image tag parameters used in TIFF file creation. Includes fields for image dimensions, sample properties, compression, and other metadata.

```rust
pub struct ImageTagParams<'a> {
    pub width: u32,
    pub height: u32,
    pub samples_per_pixel: u16,
    pub bits_per_sample: u16,
    pub sample_format: u16,
    pub compression: u16,
    pub photometric: u16,
    pub predictor: u16,
    pub planar_configuration: u16,
    pub subfile_type: u32,
    pub extra_tags: &'a [Tag],
    pub offsets_tag_code: u16,
    pub byte_counts_tag_code: u16,
    pub num_blocks: usize,
    pub layout_tags: &'a [Tag],
    pub is_bigtiff: bool,
}
```

--------------------------------

### u64 Implementation for TiffWriteSample

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/sample/trait.TiffWriteSample.html

Implements the TiffWriteSample trait for the u64 type. Specifies that u64 samples have a format code of 1, 64 bits per sample, and 8 bytes per sample.

```rust
const SAMPLE_FORMAT: u16 = 1;
    const BITS_PER_SAMPLE: u16 = 64;
    const BYTES_PER_SAMPLE: usize = 8;

    fn encode_slice(samples: &[Self], byte_order: ByteOrder) -> Vec<u8>;

```

--------------------------------

### and_then

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Calls op if the result is Ok, otherwise returns the Err value of self.

```APIDOC
## and_then

### Description
Calls `op` if the result is `Ok`, otherwise returns the `Err` value of `self`. This function can be used for control flow based on `Result` values.

### Method
`and_then<U, F>(self, op: F) -> Result<U, E>` where `F: FnOnce(T) -> Result<U, E>`

### Parameters
- **op** (`FnOnce(T) -> Result<U, E>`) - A closure that takes the `Ok` value and returns a `Result`.

### Request Example
```rust
// Example usage would depend on a specific closure implementation.
// let result = some_result.and_then(|value| process_value(value));
```

### Response
#### Success Response
- `Result<U, E>`: Returns the result of the closure `op` if `self` is `Ok`, otherwise returns the `Err` value of `self`.

#### Response Example
```rust
// If self is Ok(value) and op(value) returns Ok(new_value), returns Ok(new_value)
// If self is Ok(value) and op(value) returns Err(error), returns Err(error)
// If self is Err(error), returns Err(error)
```
```

--------------------------------

### Configure Predictor

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/builder/struct.ImageBuilder.html

Sets the predictor for compression, which can improve compression ratios for certain data types. Common predictors include None and Horizontal Differencing.

```rust
pub fn predictor(self, p: Predictor) -> Self
```

--------------------------------

### into_err

Source: https://docs.rs/tiff-writer/0.2.5/tiff_writer/error/type.Result.html

Returns the contained Err value, but never panics. This is an experimental API.

```APIDOC
## into_err

### Description
Returns the contained `Err` value, but never panics. Unlike `unwrap_err`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap_err` as a maintainability safeguard that will fail to compile if the ok type of the `Result` is later changed to a type that can actually occur.

### Method
`into_err()`

### Parameters
None

### Request Example
```rust
fn only_bad_news() -> Result<!, String> {
    Err("Oops, it failed".into())
}

let error: String = only_bad_news().into_err();
println!("{error}");
```

### Response
#### Success Response
- `E`: The contained `Err` value.

#### Response Example
```rust
// If Err("Oops, it failed"), returns "Oops, it failed"
```
```
Tokens:
Raw