stb-image

  1. stb-image
  2. Repository
  3. API
    1. Examples
    2. Known limitations
      1. backwards seek not implemented

This is a CHICKEN egg that wraps stb_image.h version 2.19 from Sean Barrett and friends. It works on CHICKEN 4 and 5.

Repository

https://github.com/kristianlm/chicken-stb-image

API

  1. stb-image
  2. Repository
  3. API
    1. Examples
    2. Known limitations
      1. backwards seek not implemented
[procedure] (read-image #!key channels)
[procedure] (load-image u8vector #!key channels)

Decodes an image into raw pixel data. read-image reads the image from from (current-input-port) while load-image gets this from the provided u8vector. The image type is detected by content, and may be: JPEG, PNG, TGA, BMP, PSD, GIF, HDR, PIC, PNM as explained in the heading comments of stb_image.h.

Both procedures return 4 values:

  1. raw pixel data (as u8vector)
  2. width
  3. height
  4. number of channels

You can force the number of channels with the channels keyword. If channels is #f or not given, the number of channels in the original image will be used.

The size of the pixel data blob is always (* width height channels) bytes. The first pixel is the top-left-most in the image. Each pixel is channel number of bytes long. The number of channels define the pixel color, interleaved as follows:

  1. grey
  2. grey, alpha
  3. red, green, blue
  4. red, green, blue, alpha

read-image may read beyond the image data, so the data in current-input-port should contain only one image.

[procedure] (read-image-info)
[procedure] (load-image-info blob)

Like read-image and load-image, but does not load pixel data and should be faster. Returns three values:

  1. width
  2. height
  3. number of channels

Note that on 32-bit systems, blobs cannot be larger than 16M. This limits image sizes as pixel data is stored as blobs.

Examples

For quick testing, you can read PNGs from ImageMagick's convert:

   $ convert -size 4x4 xc:blue -draw 'line 0,0 4,4' png:- | csi -R stb-image -p '(read-image)'
   #u8(0 0 0     0 0 234   0 0 255   0 0 255
       0 0 234   0 0 0     0 0 234   0 0 255
       0 0 255   0 0 234   0 0 0     0 0 234
       0 0 255   0 0 255   0 0 234   0 0 0)
   4
   4
   3

Which reveal the black line along the diagonal and informs that the image is 4x4 with 3-channels.

Known limitations

backwards seek not implemented

Some special-case images try to seek backwards in the internal API. This hasn't been implemented due to increased complexity: you may see a "backwards seek not implemented" error. If this is a show-stopper, contact the author.