Pictures (MIT 6.001 implementation only)
========================================

A picture data object is a two-dimensional array of real numbers that represents a grey-scale image on the screen.  The grey level that the value of each element represents is determined relative to the range of values of the array.

The width of a picture is the number of elements in each row and the height is the number of elements in each column.  The elements are referenced by giving the horizontal component first and the vertical one second, with the origin at the bottom left corner of the displayed picture.

Coordinates (I, J) are valid coordinates of picture P if and only if:

     (and (exact-nonnegative-integer? I)
          (exact-nonnegative-integer? J)
          (< I (picture-width P))
          (< J (picture-height P)))

Construction of Pictures
------------------------

make-picture and procedure->picture are simple ways to make pictures.  picture-map is a way to create a new picture by applying a procedure to one or more pictures.  Pictures can also be made by reading files: see pgm-file->picture.

 -- procedure+: make-picture x y [k]
     X and Y must be exact positive integers and K, if specified, must be a real number.  Returns a picture of width X and height Y.  If K is specified then each picture element is initialized to K, otherwise the elements are unspecified.

 -- procedure+: procedure->picture x y f
     X and Y must be exact positive integers, and F must be a real-valued procedure of two variables.  Returns a picture of width X and height Y, where the value of each element is the result of applying F to the element's coordinates.

 -- procedure+: picture-map f picture ...
     F must be a procedure, and all of the PICTURE arguments must have the same dimensions.  Returns a newly allocated picture, each element of which is obtained by calling F, passing it as arguments the corresponding element of each PICTURE argument.  (Thus F must accept the same number of arguments as there are PICTURE arguments to picture-map.)

     In other words, each element could have been initialized as follows:

          (picture-set! RESULT I J
                        (F (picture-ref PICTURE I J) ...))

Manipulating Pictures
---------------------

 -- procedure+: picture? object
     Returns #t if OBJECT is a picture, otherwise returns #f.

 -- procedure+: picture-width picture
 -- procedure+: picture-height picture
     These procedures return the width and height, respectively, of PICTURE.

 -- procedure+: picture-min picture
 -- procedure+: picture-max picture
     These procedures return, respectively, the least and the greatest values stored in PICTURE.

 -- procedure+: picture-ref picture i j
     Returns the value of element (I,J) of PICTURE (always a real number).  I and J must be valid coordinates for PICTURE.

 -- procedure+: picture-set! picture i j k
     Stores K at element (I,J) in PICTURE and returns an unspecified value.  K must be a real number and I and J must be valid coordinates for PICTURE.

Displaying Pictures
-------------------

To display pictures, an X graphics window must first be created. Although any window may be used, the colormap will not be guaranteed to be correct for grey-scale pictures, therefore the recommended way of creating windows for displaying pictures is to use the make-window procedure.

 -- procedure+: picture-display w picture [min [max]]
     Displays, in the graphics device W, the largest integer scaling of PICTURE that can be contained in W.  If MIN and MAX are specified then the grey levels will be computed using these values as PICTURE's minimum and maximum values, otherwise the actual least and greatest values of PICTURE will be used.  The value returned by this procedure is unspecified.

 -- procedure+: make-window w h x y
     Returns a graphics device of width W, height H and screen position X,Y (as would be given in an X geometry string) with a grey-scale colormap attached.

Saving and Restoring Pictures
-----------------------------

Pictures can be read from or written to files in PGM format using the following procedures.

 -- procedure+: pgm-file->picture pathname
     Reads a grey-scale image stored in PGM format from the file PATHNAME, returning a picture whose graphical representation will closely resemble that of the saved image.

 -- procedure+: picture->pgm-file picture pathname
     Saves PICTURE in PGM format in the file PATHNAME. Overwrites any previously existing file of that name.