section p of routines in png.i

functions in png.i - p

png_map


    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.  
  
   Interpreted function, defined at i0/png.i   line 367

SEE ALSO: png_pcal, png_scale, png_read, png_write

png_pcal


    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.  
  
   Interpreted function, defined at i0/png.i   line 430

SEE ALSO: png_scale, png_write, png_read

png_read


    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.  
  
   Interpreted function, defined at i0/png.i   line 8

SEE ALSO: png_map, png_read, png_write

png_write


    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.  
  
   Interpreted function, defined at i0/png.i   line 76