Errors

cl-atlas signals atlas-error when it cannot do what was asked, with a message that says what went wrong and what to do. atlas-error-message returns the message.

(handler-case (atlas:atlas-add atlas image)
  (atlas:atlas-error (condition)
    (format *error-output* "~A~%" condition)))

Messages

An image larger than a page. The padding is kept right of and below every image, at a page's edges too, so the largest image is the page size less the padding:

An image of 16 by 16 texels does not fit a page of 16 by 16 with 1 of
padding.  Make the atlas with a larger :PAGE-SIZE.

Rows of no whole number of texels. A row of an image holds its texels' bytes, atlas-channels each:

An image's rows hold 6 bytes, which is no whole number of texels of 4
bytes.

An image that is no 2D array, returned by the function given to atlas-find-or-add. An image is indexed by row and then by byte:

An image is a 2D array of octets, rows by bytes, not (SIMPLE-ARRAY
(UNSIGNED-BYTE 8) (5)).

atlas-add declares its image's type, so an image given to it that is no 2D array is a type-error instead: see Wrong types.

A page that does not exist, from atlas-page:

#<ATLAS 1 page of 512x512 {1203...}> has 1 page, so it has no page 3.

A rectangle outside its page, from copy-page-region:

The rectangle at 500, 500 of 20 by 20 is not inside #<PAGE 0, 512x512
{1203...}>.

Wrong types

Arguments of the wrong type signal type-error. The public functions declare their arguments' types, and SBCL checks them on entry: a :channels of 5, an index that is no integer, a key function that is no function, and an image for atlas-add that is no 2D array of octets, such as a vector or an array of element type t. SBCL words the message:

The value
  #(0 0 0 0 0)
is not of type
  (ARRAY (UNSIGNED-BYTE 8) (* *))
when binding CL-ATLAS::PIXELS