You are looking at historical revision 39572 of this page. It may differ significantly from its current revision.

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

chicken-stb-image

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

 [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.