functions in yorz.i -

             jpeg2, name  
 
     writes the picture in the current graphics window to the jpeg file  
     NAME, or to NAME+".jpg" is NAME does not end in ".jpg".  

             image = jpeg_read(filename)  
         or image = jpeg_read(filename, comments)  
         or shape = jpeg_read(filename, comments, [0,0,0,0])  
         or image = jpeg_read(filename, comments, subset)  
 
    
  Read jpeg file FILENAME.  The returned IMAGE is 3-by-width-by-height  
  for rgb images (the usual case) or just width-by-height for grayscale  
  images.  Note that the scanline order is top-to-bottom.  
  If COMMENTS is present, it must be a simple variable reference.  
  That variable will be set to either nil or a string array containing  
  all the descriptive comments in the file.  
    
  In the third form, the return value is [nchan,width,height] instead  
  of the image, where nchan=1 or nchan=3.  
  In the fourth form, SUBSET is [i0,i1,j0,j1] and the returned image is  
  the subset full_image(..,i0:i1,j0:j1) of the full image.  (This is  
  inefficient, but, for example, some Mars Rover pictures released by  
  NASA are inconveniently large.)  
    

             jpeg_write, filename, image  
         or jpeg_write, filename, image, comments, quality  
 
    
  Write jpeg file FILENAME containing IMAGE at the specified QUALITY.  
  The default QUALITY is 75; the range is from 0 to 100.  The IMAGE  
  can be either 3-by-width-by-height for rgb or width-by-height for  
  grayscale.  Note that scanline order is top-to-bottom.  
  If COMMENTS is non-nil, it is a string or an array of strings that  
  will be written as descriptive comments in the jpeg file.  
    

             png2, name  
 
     writes the picture in the current graphics window to the png file  
     NAME, or to NAME+".png" is NAME does not end in ".png".  

             image = png_map(full_image, nfo)  
 
    maps FULL_IMAGE to png-stored values, according to the  
    pCAL information in NFO.  
    The NFO parameter may be either the array of pointers as returned by  
    png_read, or an array of reals as for *nfo(4) (see png_read).  
    You can use png_pcal to compute an NFO mapping tailored to IMAGE.  
    

             pcal = png_pcal(image)  
         or pcal = png_pcal(image, depth)  
 
    
  KEYWORDS: cmin=, cmax=, res=, log=  
    cmin, cmax   clip image to these minimum and maximum values  
    res          image "resolution", or minimum step size  
    log          non-zero forces log map if image all positive  
                 or all negative  
    
    returns 8-element pCAL png mapping for IMAGE, appropriate for  
    use as pcal= keyword in png_write.  The png_map function applies  
    pcal to produce the as-stored char or short array; the png_scale  
    function applies pcal to recreate the original IMAGE from the  
    as-stored array.  
    
    There are three kinds of pCAL mappings: linear, log, and asinh.  
    Linear and log scales are familiar; the asinh scale is a modified  
    log scale that can be used for arrays that change sign:  
    
    linear:  image = a*stored + b  
    log:     image = b * exp(a*stored)  
    asinh:   image = b * sinh(a*(stored - mx/2))  
    
    You can specify a bit DEPTH for the stored array, which can be  
    between 2 and 16 inclusive.  For bit depth 1, just threshhold  
    the image (image>const_thresh).  By default, for integer IMAGE,  
    DEPTH is the smallest depth that covers the range of IMAGE values,  
    but never more than 16.  For float or double IMAGE, the default  
    DEPTH is always 16.  
    
    If IMAGE has any integer data type, the pCAL mapping will always  
    be linear; use IMAGE+0.0 if you want a log or asinh map.  
    
    The png pCAL definition allows b<0 in the log scale, so it can  
    be used for image values that are either all positive or all  
    negative.  In either case, the integer stored values take equal  
    ratio steps from the minimum to the maximum image values (or  
    cmin and cmax).  For the linear scale, of course, each step in  
    the stored integer represents an constant increment in the image  
    value.  The asinh scale is a logarithmic ratio scale for stored  
    values near 0 or mx (the maximum stored integer value), reverting  
    to a linear scale near the middle of its range where the image  
    value passes through zero.  
    
    To get the asinh scale, you must specify the res= keyword:  
    You must specify the smallest step size for the asinh scale by  
    setting the res= keyword.  For a log scale, the res= value will  
    replace the actual minimum array value or cmin value (or cmax if  
    image is all negative values), clipping any smaller absolute values.  
    If mx is large enough to cover the whole scale with the given res=  
    value in linear steps, a linear scale will be used.  
    
    You can specify log=1 to force log scaling if image is all  
    positive or all negative.  
    

             image = png_read(filename)  
         or image = png_read(filename, depth, nfo)  
 
    
  Read png file FILENAME.  The returned IMAGE is either an array  
  of char or short, unless type= is specified (see below).  
  The IMAGE may have a leading dimension of 2 if it is gray+alpha,  
  3 if it is rgb, or 4 if it is rgba.  
  In the second form, DEPTH and NFO must be simple variable references.  
  NFO is set to a pointer array to descriptive information by png_read:  
  *nfo(1) = PLTE 3-by-N char array of palette rgb values  
  *nfo(2) = tRNS char array of alpha (opacity) values corresponding  
                  to PLTE or single gray or rgb short value (transparent)  
  *nfo(3) = bKGD single gray or rgb short value  
               note that bKGD and the single value tRNS have the same  
               range and meaning as a pixel value, in particular,  
               for a pseudocolor image, they represent a palette index  
  *nfo(4) = pCAL [x0,x1,max,eqtype,p0,p1,p2,p3,...] physical pixel value  
                  relation between pixel value and physical value  
                  array of double values (see below for meaning)  
  *nfo(5) = pCAL [calibration_name, unit_name] string pair  
  *nfo(6) = sCAL [wide,high,sunit] physical scale of pixels as scanned  
                  or printed, sunit 1.0 for meters or 2.0 for radians  
  *nfo(7) = pHYs long [n_xpix,n_ypix,per_meter] values  
                  n_xpix,n_ypix are pixels per unit,  
                  per_meter is 0 for aspect ratio only, 1 for meters  
  *nfo(8) = tEXt (or zTXt or iTXt) 2-by-N string array of (key,text)  
  *nfo(9) = tIME string value image modification time  
  any or all of these NFO values may be nil.  The four character  
  designators (e.g. PLTE) are the png chunk names for the corresponding  
  information.  
    
  pCAL array of doubles has following meaning:  
     max = 2^depth-1  
     original = long( floor( (image(i)*(x1-x0)+long(max)/2) / max ) ) + x0  
     image(i) = long( floor( ((original-x0)*max+long(x1-x0)/2) / (x1-x0) ) )  
     eqtype = 0   physical = p0 + p1*original/(x1-x0)  
     eqtype = 1   physical = p0 + p1*exp(p2*original/(x1-x0))  
     eqtype = 2   physical = p0 + p1*p2^(original/(x1-x0))  
     eqtype = 3   physical = p0 + p1*sinh(p2*(original-p3)/(x1-x0))  
    
  If the type= keyword is non-nil and non-zero, the returned value  
  is as if png_scale(image, nfo, type=type), which scales the raw image  
  according to the information in pCAL, or is a no-op if pCAL does  
  not exist.  
    

             image = png_scale(raw_image, nfo, type=type)  
 
    scales RAW_IMAGE to type TYPE (char, short, int, long, float, or  
    double, according to the pCAL information in NFO.  The NFO  
    parameter may be either the array of pointers returned by  
    png_read, or an array of reals as for *nfo(4) (see png_read).  
    

             png_write, filename, image  
         or png_write, filename, image, depth, nfo  
 
    
  Write png file FILENAME containing IMAGE at the specified DEPTH.  
  The default DEPTH is 8 bits.  For grayscale IMAGE, 1<=DEPTH<=16,  
  otherwise depth is 8 or 16.  If NFO is specified, it is an  
  array of pointers as described in the help for png_read.  You can  
  optionally specify the same information as keywords:  
    palette=[[r0,g0,b0],[r1,g1,b1],...]  
    alpha=[a0,a1,...] if image is simple 2D and palette specified  
    trns=value       if image is gray (no palette)  
         [r,g,b]     if image is color  
         illegal if image has alpha channel  
    bkgd=value or [r,g,b] suggested background color  
      note that bkgd and trns have the same range and meaning as a  
      pixel value, in particular, for a pseudocolor, a palette index  
    pcal=[x0,x1,max,eqtype,p0,p1,p2,p3,...]  
    pcals=[calibration_name, unit_name]  as for pCAL (see png_read)  
    scal=[wide,high,sunit]  as for sCAL (see png_read)  
    phys=[n_xpix,n_ypix,per_meter]  as for pHYs (see png_read)  
    text=[[key1,text1],[key1,text1],...]  
      recognized keys are: Title, Author, Description, Copyright,  
      Creation Time, Software, Disclaimer, Warning, Source (a device),  
      and Comment  
    time=string  modification time (timestamp() is default)  
  When both NFO and keywords are supplied, the keywords override any  
  corresponding value in nfo.  
    
  If IMAGE has a data type other than short or char, a default pCAL  
  will be supplied if it is a simple grayscale (2D) image.  If DEPTH  
  is not supplied, it defaults to 8 if IMAGE is type char and/or if  
  a palette is supplied, or to 16 otherwise.  
    

             crc32 = z_crc32(crc32, data)  
         or adler32 = z_crc32(adler32, data, 1)  
 
    
  Compute the crc32 or adler32 checksum of DATA.  The first  
  argument can be [] (nil) if this is the first chunk of DATA;  
  to checksum a long stream of data you can call z_crc32 on  
  a series of chunks, feeding the result of each call as input  
  to the following call.  
    

             buffer = z_deflate()  
         or buffer = z_deflate(level)  
         or buffer = z_deflate(level, dictionary)  
 
      then navail = z_deflate(buffer, data)  
        or zdata = z_flush(buffer)  
   finally zdata = z_flush(buffer, data)  
        or zdata = z_flush(buffer, -)  
    
  In any of the first three forms, initiate a zlib deflation  
  BUFFER.  The second two forms allow you to specify a compression  
  LEVEL (0-9 in increasing compression and decreasing speed), and/or  
  a special compression DICTIONARY (which you will need to supply  
  again in order to decompress the data later).  
    
  After the BUFFER has been created, use z_deflate to compress DATA,  
  adding it to the compressed stream in the BUFFER.  After one or  
  several calls to z_deflate, you can call z_flush in the first form  
  to extract the current BUFFER contents as ZDATA, the portion of  
  the compressed data stream stored in BUFFER.  You can alternate  
  calls to z_deflate and z_flush as many times as you like in order  
  to compress an arbitrary amount of DATA into ZDATA without filling  
  memory.  The NAVAIL returned by z_deflate is a lower limit on the  
  number of bytes of compressed data a subsequent z_flush will return.  
    
  The final block of DATA must be compressed by a call to z_flush,  
  in the final form.  This flushes all remaining data into the  
  resulting ZDATA and closes the BUFFER.  You can call z_flush  
  in this form immediately after creating the buffer, so that  
  the tersest way to compress a single block of data is:  
         zdata = z_flush(z_deflate(), data)  
  Use - for DATA to indicate you have no more DATA, but want to  
  finish the compression.  
    

             zdata_or_data = z_flush(buffer)  
         or zdata = z_flush(buffer, data)  
         or zdata = z_flush(buffer, -)  
         or data = z_flush(buffer, type)  
 
    
  Flushes all available ZDATA (if STATE is a z_deflate state) or  
  all available DATA (if STATE is a z_inflate state).  For z_deflate  
  states, a second argument to z_flush is the final DATA block to  
  complete the ZDATA stream.  For z_inflate states, you may specify  
  an array data TYPE so that the return DATA value will have that  
  data type instead of char.  
    

             buffer = z_inflate()  
 
      then flag = z_inflate(buffer, zdata)  
        or flag = z_inflate(buffer, zdata, data)  
        or data = z_flush(buffer)  
        or data = z_flush(buffer, type)  
    
  In the first form, initiate a zlib inflation BUFFER.  You use  
  that BUFFER in subsequent calls to z_inflate if you do not know  
  in advance how large the uncompressed DATA will be, or if you  
  want to do the decompression in chunks to conserve memory.  
    
  Use the second or third forms to actually decompress ZDATA.  
  After one or more calls to z_inflate, you can call z_flush in  
  order to extract whatever uncompressed DATA has so far been  
  produced.  You can optionally specify a TYPE array for  
  z_flush, otherwise the DATA will be a 1D array of char.  
    
  Alternatively, you can supply a DATA array as the third parameter  
  to z_inflate, in which case z_inflate will uncompress to your DATA  
  array instead of to an internal array in BUFFER.  You can use this  
  form if you already know the size and data type the data will  
  decompress to.  If the returned flag is 3, you can call z_setdict  
  and repeat the call.  Otherwise, a return value other than 0  
  probably represents an error.  Note that z_flush will not return  
  bytes that have been written to a DATA array supplied to z_inflate.  
    
  The FLAG returned by z_inflate is  
    0  if the ZDATA stream is complete, in which case no  
       further calls to z_inflate are legal with that BUFFER  
       - the next call to z_flush will return all remaining  
         bytes of the uncompressed data  
    1  if the ZDATA stream is incomplete, but no additional  
       uncompressed data is yet available in BUFFER  
    2  if the ZDATA stream is incomplete, and uncompressed data  
       can be retrieved from BUFFER by calling z_flush  
    3  if a DICTIONARY is required to continue decompression  
       - use z_setdict to set a dictionary and call z_inflate  
         a second time with the same DATA  
   -1  if the ZDATA stream completed, but contained additional  
       bytes after the end  
   -2  if the ZDATA stream is corrupted  
    

             adler32 = z_setdict(buffer)  
         or flag = z_setdict(buffer, dictionary)  
 
    
  In the first form, returns the adler32 checksum of the dictionary  
  required to continue decompressing a stream after z_inflate  
  returns 3, or [] (nil) if BUFFER does not need a dictionary.  
  You can also use this form to retrieve the adler32 checksum of  
  a dictionary you supplied in the call to z_deflate that  
  returned BUFFER.  
    
  In the second form, sets the DICTIONARY for BUFFER so that  
  succeeding calls to z_inflate can continue decompressing.  The  
  return value FLAG is 1 on success, or 0 on failure.  
    
  You can compute the adler32 checksum using the z_crc32 function.