pngleam

Types

ColourData

A representation of any possible colour value that can be contained within a PNG image.

pub type ColourData {
  IndexedData(i: Int)
  GreyscaleData(v: Int, a: option.Option(Int))
  ColourData(r: Int, g: Int, b: Int, a: option.Option(Int))
}

Constructors

```
IndexedData(i: Int)
```
The pixel data for an indexed image, representing the index in the colour palette of that image.
```
GreyscaleData(v: Int, a: option.Option(Int))
```
The pixel data for a greyscale value, optionally with an alpha value if the image is of that colour type.
```
ColourData(r: Int, g: Int, b: Int, a: option.Option(Int))
```
The pixel data for a full colour RGB value, optionally with an alpha value if the image is of that colour type.

ColourType

</>

The type of colour used for a PNG image.

pub type ColourType {
  Indexed
  Greyscale(alpha: Bool)
  Colour(alpha: Bool)
}

Constructors

```
Indexed
```
The image uses a fixed colour palette, and each pixel stores the index into that palette.
```
Greyscale(alpha: Bool)
```
The image can only represent grey values.
```
Colour(alpha: Bool)
```
The image can represent full colour values.

PngImage

</>

The parsed contents of a PNG image.

pub type PngImage {
  PngImage(
    metadata: PngMetadata,
    palette: option.Option(List(Rgb)),
    image_data: List(BitArray),
    other_data: List(#(BitArray, BitArray)),
  )
}

Constructors

PngImage(
  metadata: PngMetadata,
  palette: option.Option(List(Rgb)),
  image_data: List(BitArray),
  other_data: List(#(BitArray, BitArray)),
)

PngMetadata

</>

The information found in the initial header (IHDR) chunk of a PNG image.

pub type PngMetadata {
  PngMetadata(
    width: Int,
    height: Int,
    colour_type: ColourType,
    bit_depth: Int,
  )
}

Constructors

PngMetadata(
  width: Int,
  height: Int,
  colour_type: ColourType,
  bit_depth: Int,
)

PngParseError

</>

The possible error states when parsing a PNG image.

pub type PngParseError {
  InvalidSignature
  ChecksumMismatch
  MissingHeaderChunk
  InvalidChunkData
  InvalidColourType
  InvalidParsedBitDepth
  InvalidCompressionType
  InvalidFilterMethod
  InvalidInterlaceMethod
  UnsupportedInterlaceMethod
  InvalidPalette
  InvalidRowFilterType
  InvalidRowData
  InvalidDeflateData
}

Constructors

```
InvalidSignature
```
The signature was not that of a PNG image but of a different file type.
```
ChecksumMismatch
```
The checksum calculated for a chunk in the PNG did not match the one provided for that chunk.
```
MissingHeaderChunk
```
The image was missing a header (IHDR) chunk.
```
InvalidChunkData
```
A chunk in the image was not in the correct format.
```
InvalidColourType
```
The colour type in the image was not one of the valid types (0, 2, 3, 4, and 6).
```
InvalidParsedBitDepth
```
The bit depth in the image was not valid for the colour type being used.
```
InvalidCompressionType
```
The compression type in the image was not one of the valid types (0).
```
InvalidFilterMethod
```
The filter method in the image was not one of the valid types (0).
```
InvalidInterlaceMethod
```
The interlace method in the image was not one of the valid type (0 and 1).
```
UnsupportedInterlaceMethod
```
The interlace method used by the image is not supported by the parser. Only 0 (no interlacing) is supported.
```
InvalidPalette
```
The palette data was invalid.
```
InvalidRowFilterType
```
The row filter type was not one of the valid values (0, 1, 2, 3, and 4).
```
InvalidRowData
```
The row data was invalid.
```
InvalidDeflateData
```
The image data was not valid deflate data (i.e. missing zlib headers).

PngRenderError

</>

The possible error states when creating a new PNG image.

pub type PngRenderError {
  UnalignedData
  InvalidBitDepth
  InvalidCompressionLevel
}

Constructors

```
UnalignedData
```
The data provided was not byte-aligned.
```
InvalidBitDepth
```
The bit depth provided was not valid for the colour type being used.
```
InvalidCompressionLevel
```
The compression level was not within the supported range (0-9)

Rgba

</>

A colour with red, green, blue, and alpha components.

pub type Rgba {
  Rgba(r: Int, g: Int, b: Int, a: Int)
}

Constructors

```
Rgba(r: Int, g: Int, b: Int, a: Int)
```

Values

fold_colour_pixels

</>

pub fn fold_colour_pixels(
  png: PngImage,
  state state: state,
  with fun: fn(state, Int, Int, Rgb) -> state,
) -> Result(state, Nil)

Fold over all the pixels in a parsed PNG image with an RGB colour type.

The callback gets the X and Y position of the pixel, (where 0,0 is the top-left) along with the RGB pixel value.

The fold starts at the top and goes over each row, left to right, top to bottom.

Returns an error if the provided PNG is not the correct colour type or is an invalid bit depth for this colour type.

fold_greyscale_pixels

</>

pub fn fold_greyscale_pixels(
  png: PngImage,
  state state: state,
  with fun: fn(state, Int, Int, Int) -> state,
) -> Result(state, Nil)

Fold over all the pixels in a parsed PNG image with a greyscale colour type.

The callback gets the X and Y position of the pixel, (where 0,0 is the top-left) along with the greyscale pixel value.

The fold starts at the top and goes over each row, left to right, top to bottom.

Returns an error if the provided PNG is not the correct colour type or is an invalid bit depth for this colour type.

fold_indexed_pixels

</>

pub fn fold_indexed_pixels(
  png: PngImage,
  state state: state,
  with fun: fn(state, Int, Int, Int) -> state,
) -> Result(state, Nil)

Fold over all the pixels in a parsed PNG image with an indexed colour type.

An indexed image is one where a colour palette is specified for the image, and the pixel data just references the index within that palette.

The callback gets the X and Y position of the pixel, (where 0,0 is the top-left) along with the indexed pixel value.

The fold starts at the top and goes over each row, left to right, top to bottom.

Returns an error if the provided PNG is not the correct colour type or is an invalid bit depth for this colour type.

fold_transparent_colour_pixels

</>

pub fn fold_transparent_colour_pixels(
  png: PngImage,
  state state: state,
  with fun: fn(state, Int, Int, Rgba) -> state,
) -> Result(state, Nil)

Fold over all the pixels in a parsed PNG image with an RGBA colour type.

The callback gets the X and Y position of the pixel, (where 0,0 is the top-left) along with the RGBA pixel value.

The fold starts at the top and goes over each row, left to right, top to bottom.

Returns an error if the provided PNG is not the correct colour type or is an invalid bit depth for this colour type.

fold_transparent_greyscale_pixels

</>

pub fn fold_transparent_greyscale_pixels(
  png: PngImage,
  state state: state,
  with fun: fn(state, Int, Int, Va) -> state,
) -> Result(state, Nil)

Fold over all the pixels in a parsed PNG image with a greyscale+alpha colour type.

The callback gets the X and Y position of the pixel, (where 0,0 is the top-left) along with the greyscale+alpha pixel value.

The fold starts at the top and goes over each row, left to right, top to bottom.

Returns an error if the provided PNG is not the correct colour type or is an invalid bit depth for this colour type.

parse_metadata

</>

pub fn parse_metadata(
  data: BitArray,
) -> Result(PngMetadata, PngParseError)

Parse only the metadata chunk at the start of the PNG.

parse_png

</>

pub fn parse_png(
  data: BitArray,
) -> Result(PngImage, PngParseError)

Parse the PNG into a list of bit arrays representing each row of the image.

read_colour_pixel_row

</>

pub fn read_colour_pixel_row(
  row: BitArray,
  bit_depth: Int,
) -> Result(List(Rgb), Nil)

Read a single row of pixels from a PNG image with an RGB colour type.

Returns an error if the provided bit depth is invalid for this colour type.

read_greyscale_pixel_row

</>

pub fn read_greyscale_pixel_row(
  row: BitArray,
  bit_depth: Int,
) -> Result(List(Int), Nil)

Read a single row of pixels from a PNG image with a greyscale colour type.

Returns an error if the provided bit depth is invalid for this colour type.

read_indexed_pixel_row

</>

pub fn read_indexed_pixel_row(
  row: BitArray,
  bit_depth: Int,
) -> Result(List(Int), Nil)

Read a single row of pixels from a PNG image with an indexed colour type.

An indexed image is one where a colour palette is specified for the image, and the pixel data just references the index within that palette.

Returns an error if the provided bit depth is invalid for this colour type.

read_pixel_at

</>

pub fn read_pixel_at(
  png: PngImage,
  x x: Int,
  y y: Int,
) -> Result(ColourData, Nil)

Returns the pixel at a specific x,y coordinate in the image (where 0,0 is the top left).

Returns an error if no pixel data was found at the given location.

read_transparent_colour_pixel_row

</>

pub fn read_transparent_colour_pixel_row(
  row: BitArray,
  bit_depth: Int,
) -> Result(List(Rgba), Nil)

Read a single row of pixels from a PNG image with an RGBA colour type.

Returns an error if the provided bit depth is invalid for this colour type.

read_transparent_greyscale_pixel_row

</>

pub fn read_transparent_greyscale_pixel_row(
  row: BitArray,
  bit_depth: Int,
) -> Result(List(Va), Nil)

Read a single row of pixels from a PNG image with a greyscale+alpha colour type.

Returns an error if the provided bit depth is invalid for this colour type.

render_colour_png

</>

pub fn render_colour_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  state state: state,
  pixel plot: fn(state, Int, Int) -> #(state, Rgb),
  compression_level compression_level: option.Option(Int),
) -> Result(#(state, BitArray), PngRenderError)

Create a PNG image with the RGB colour type by iterating over each pixel with some state.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left) along with the current state.

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

render_greyscale_png

</>

pub fn render_greyscale_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  state state: state,
  pixel plot: fn(state, Int, Int) -> #(state, Int),
  compression_level compression_level: option.Option(Int),
) -> Result(#(state, BitArray), PngRenderError)

Create a PNG image with the greyscale colour type by iterating over each pixel with some state.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left) along with the current state.

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

render_indexed_png

</>

pub fn render_indexed_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  palette palette: List(Rgb),
  state state: state,
  pixel plot: fn(state, Int, Int) -> #(state, Int),
  compression_level compression_level: option.Option(Int),
) -> Result(#(state, BitArray), PngRenderError)

Create a PNG image with the indexed colour type by iterating over each pixel with some state.

An indexed image is one where a colour palette is specified for the image, and the pixel data just references the index within that palette that each pixel should be.

Each pixel value should be a number between 0 and one less than the length of the colour palette.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left) along with the current state.

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

render_png_raw_data

</>

pub fn render_png_raw_data(
  data data: BitArray,
  width width: Int,
  height height: Int,
  colour_type colour_type: ColourType,
  bit_depth bit_depth: Int,
  palette palette: option.Option(List(Rgb)),
  compression_level compression_level: option.Option(Int),
) -> Result(BitArray, PngRenderError)

Create a PNG image from a bit array containing raw uncompressed pixel data.

The data should already have the necessary byte at the start of each line specifying the filter type used for the data of that line as this will not be added and the data will be compressed as-is, chunked, and then put in the final image.

The compression level should either be some value between 0 (no compression) and 9 (maximum compression) or be None to be left at the default compression level (typically around 6).

render_png_rows

</>

pub fn render_png_rows(
  rows rows: List(BitArray),
  width width: Int,
  height height: Int,
  colour_type colour_type: ColourType,
  bit_depth bit_depth: Int,
  palette palette: option.Option(List(Rgb)),
  compression_level compression_level: option.Option(Int),
) -> Result(BitArray, PngRenderError)

Create a PNG image from a list of BitArrays each representing the raw uncompressed pixel data of a single row of the image (from top to bottom).

No filtering will be applied to the line data, so if a specific filter type is desired then the render_png_raw_data function should be used with the filtering already applied to each line.

The compression level should either be some value between 0 (no compression) and 9 (maximum compression) or be None to be left at the default compression level (typically around 6).

render_transparent_colour_png

</>

pub fn render_transparent_colour_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  state state: state,
  pixel plot: fn(state, Int, Int) -> #(state, Rgba),
  compression_level compression_level: option.Option(Int),
) -> Result(#(state, BitArray), PngRenderError)

Create a PNG image with the RGBA colour type by iterating over each pixel with some state.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left) along with the current state.

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

render_transparent_greyscale_png

</>

pub fn render_transparent_greyscale_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  state state: state,
  pixel plot: fn(state, Int, Int) -> #(state, Va),
  compression_level compression_level: option.Option(Int),
) -> Result(#(state, BitArray), PngRenderError)

Create a PNG image with the greyscale+alpha colour type by iterating over each pixel with some state.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left) along with the current state.

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

simple_render_colour_png

</>

pub fn simple_render_colour_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  pixel plot: fn(Int, Int) -> Rgb,
  compression_level compression_level: option.Option(Int),
) -> Result(BitArray, PngRenderError)

Create a PNG image with the RGB colour type by iterating over each pixel.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left).

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

simple_render_greyscale_png

</>

pub fn simple_render_greyscale_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  pixel plot: fn(Int, Int) -> Int,
  compression_level compression_level: option.Option(Int),
) -> Result(BitArray, PngRenderError)

Create a PNG image with the greyscale colour type by iterating over each pixel.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left).

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

simple_render_indexed_png

</>

pub fn simple_render_indexed_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  palette palette: List(Rgb),
  pixel plot: fn(Int, Int) -> Int,
  compression_level compression_level: option.Option(Int),
) -> Result(BitArray, PngRenderError)

Create a PNG image with the indexed colour type by iterating over each pixel.

An indexed image is one where a colour palette is specified for the image, and the pixel data just references the index within that palette that each pixel should be.

Each pixel value should be a number between 0 and one less than the length of the colour palette.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left).

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

simple_render_transparent_colour_png

</>

pub fn simple_render_transparent_colour_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  pixel plot: fn(Int, Int) -> Rgba,
  compression_level compression_level: option.Option(Int),
) -> Result(BitArray, PngRenderError)

Create a PNG image with the RGBA colour type by iterating over each pixel.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left).

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.

simple_render_transparent_greyscale_png

</>

pub fn simple_render_transparent_greyscale_png(
  width width: Int,
  height height: Int,
  bit_depth bit_depth: Int,
  pixel plot: fn(Int, Int) -> Va,
  compression_level compression_level: option.Option(Int),
) -> Result(BitArray, PngRenderError)

Create a PNG image with the greyscale+alpha colour type by iterating over each pixel.

The callback gets the X and Y position of the pixel (where 0,0 is the top-left).

Rendering starts at the top and goes over each row, left to right, top to bottom.

Values outside the range supported by the provided bit depth will be clamped between 0 and the maximum value.