NAME
     img - look at a picture

SYNOPSIS
     img file

DESCRIPTION
     Img clears the panel, draws file in the middle of it, and waits.  Press
     any key to put the screen back.  The file's name appears in the status
     bar while it is up.

     The panel is one bit deep: every pixel is ink or paper, and there is
     nothing in between.  A photograph therefore does not arrive intact.  Img
     reduces it to grey, scales it down to fit, and then dithers it --
     Floyd-Steinberg error diffusion, which trades each pixel's rounding error
     to its neighbours so that a region of half-grey comes out as roughly half
     black dots.  Held at arm's length this reads as tone.  Held close it is
     visibly a pattern of dots, which is what it is.  Pictures with strong
     shapes and plain backgrounds survive this best; a low-contrast photograph
     mostly does not.

     There are no options.

FORMATS
     PBM  Portable bitmap, binary (P4).  Already one bit per pixel, so it is
          drawn as it stands -- a set bit is ink.  No scaling and no dithering:
          a bitmap larger than the panel is clipped at the right and bottom
          edges rather than shrunk.  Prepare PBMs at the panel's own size and
          they land exactly as drawn.  This is the format to use for anything
          you care about.

     JPEG, PNG, GIF
          Decoded, converted to grey, box-averaged down to fit the panel with
          the aspect ratio preserved, and dithered.  An image smaller than the
          panel is never enlarged; it sits in the middle at its own size.

     The format is decided by looking at the file, not by its name.

LIMITS
     1 MiB
          The most that is read from the file.  A larger file is truncated at
          that point, and what remains usually fails to decode.

     2048 pixels
          The largest single dimension accepted.

     1 megapixel
          The largest total.  Width times height above this is refused with a
          message rather than attempted: the decode buffer would be several
          megabytes and the wait would be long.

     These apply to the compressed formats.  A PBM is drawn straight out of
     the file it was read from, subject only to the 1 MiB read.

EXAMPLES
          img /n/local/img/pepper.pbm
          img /n/local/img/rings.png

FILES
     /n/local/img
          The pictures shipped with the deck, and a reasonable place to keep
          your own.

SEE ALSO
     slides(1), gopher(1)

NOTES
     Drawing an image is a full refresh of the panel, which takes a second or
     so and flashes black on the way.  This is the e-paper doing its
     housekeeping; a partial refresh would leave the previous screen faintly
     underneath.

     Under shell(1), switching away from a shell showing an image and back
     again redraws it.

     Gopher and slides use the same renderer, so a picture that looks right
     here looks the same everywhere on the deck.

BUGS
     The ASCII bitmap format (P1) is recognised as a PBM and then rejected by
     the header parser, so it fails with a complaint about a bad header rather
     than an honest refusal.  Convert to P4 first.

FRST Computer                                                           IMG(1)
