render_image Make .png or .ppm image from a segment image file in a series.
[General Utilities]

Make .png or .ppm image from a segment image file in a series. More...

Collaboration diagram for render_image Make .png or .ppm image from a segment image file in a series.:

Synopsis:

   render_image --help
   render_iamge in=<RecordSet> out=<target> | {outname=<ident_for_filename>}  {scaling=<scaletype>}
                {palette=<color_table>}  {type=<image_protocol>} {outid=<filename_code>}
                {tkey=<time_keyword>} {min=<scale_min>} {max=<scale_max>} {prescale=<multby>}
                {scale=<image_size_ratio>} {-c} {-u} {-w} {-x}

     in=Input data series.
     n=limit limit number of records to n from beginning or -n from end of 'in'
     out=Output data series or full path of directory or pipe via ppm program.
     outname=Output quantity name for filenames.
     scaling=Color table type, minmax, minmax99, minmaxgiven, histeq, ...,, default=MINMAX
     palette=Color table, GREY or filename, default=GREY (bad spelling as pallette still allowed)
     type=Image protocol, png, ppm, ..., default=png
     tkey=keyword name for time, default T_REC
     outid=output identifier, NONE=none, #=record counter, time=time as yyyymmdd_hhmmss, default=#
     min=Min value for scaling, default nan
     max=Max value for scaling, default nan
     prescale= value to multiply by prior to min/max scaling, default 1.0.
     scale"Reduction factor list, default 1.
     -c Crop flag, causes crop to RSUN_OBS
     -r Rotate and reposition to center and solar north
     -u use unchanged for rotation and centering
     -w use white for missing pixels, instead of black
     -x High-quality flag, sets bytespercolor to 2 instead of 1,

Render_image can make one or many images per record in the input recordset. It will make one image for each value of scale where the values are given as a comma delimited list of divisors for the dimensions of the input image array. The image file will be written to a filename created from outid_outname_type where outid is either "NONE" or "time" or "#", outname is any literal string, and type is "png" or "ppm" or if out specifies a pipe, then type may be any file type that is supported as the output of a pipeline which accepts a PPM file.

The file location is spcified with the out parameter. The target may be a seriesname in which case the image will be written into a record directory of that series. If the target seriesname is the same as the series specified in "in", then each input record will be cloned. The image will be written into a segment named "image".

If the target location begins with a "/" or "./" then the $target will be used as the path for a directory into which the image file will be written. If the target location begins with a "|" character, then the target string will be used as a pipe into which a .ppm file will be written. The pipe string will have " > <filename>" appended to it. In the case of a pipe, the string given in the 'out' parameter will be scanned for replacement tokens delimited by '{...}'. Inside the '{}' pair the following replacement instructions are available:

   The word 'ID' is replaced by the filename ID as built from outid.
   The word '%' is replaced by that percent of the height of the image rounded
       to the nearest pixel.  If the floating point number after the '%' is itself
       followed by a ':' and an integer, then that integer will be used as the
       smallest number for the replacement token.  So, for instance '{%1.2:5}'
       with the image height of 256 pixels will be processed as: 1.2% of 256 is 3.072
       which rounds to 3 which is smaller than 5 so the result will be 5.

The image filename is generated from the outid, outname, and type parameters. If outid is the string "time" then the time of the image as specified by the tkey (defaults to T_REC) will be used with the "." and ":" and "_<zone>" componenets deleted. I.e. the time will be in the form "yyyymmdd_hhmmss". The outid = time can have a suffix specifying the number of time characters to include. the format of the suffix is ":nn" where nn is from 1 to 15. If outid is a literal "#" then the "%04d" layout will be used to generate the image sequence number within the run of the program (i.e. the record number within the current recordset). If outid = NONE then the filename will be built from outname alone. The type parameter must be "png" or "ppm" unless the out parameter specifies a ppm pipeline in which case type should be the suffix for the file type generated by the pipe.

The scaling of image values to color table indices is controlled by the scaling parameter. scaling must be one of MINMAX, MAXMIN, MINMAXGIVEN, MINMAX99, MAXMIN99, HISTEQ, MAG at present. The default is MINMAX. If the scaling is MINMAX and both min and max parameters are given, then the MINMAXGIVEN scaling will be used. MINMAX99 and MAXMIN99 mean to eliminate the top and bottom 0.5% of the histogram of the values before computing a linear scaling. MAXMIN and MAXMIN99 result in a reversed scaling with the max value mapped to the first color in the table and the min value mapped to the max color in the table. String case is ignored for the scaling parameter. If prescale is set then the data will be multiplied by prescale prior to the above actions, i.e. prior to any minmax limits applied and prior to any log, sqrt, histeq, etc.

The MAG scaling uses a scaling of 400*M/pow((abs(M)+bias),0.75) bias=30, from user provided min and max (defaulting to +-1500). This scaling emphasizes low absolute field strength but still shows detail up to a max of 3000 gauss. The default of 1500 clips umbral fields with the tradeoff of more contrast for plage and network fields.

The color table is specified by the palette parameter. The table may be a built in table, at persent the only build-in is "grey". ("grey", "gray", "GREY", "GRAY" are all allowed). If not a build-in table name the palette parameter is expected to be a file path to a table of .sao or .lut types. These table formats are described in the ds9(1) documentation.

Flags:

-u: Leave orientation unchanged. Else flip-flip if CROTA2 is near 180.

-r: rotate and reposition image to frame center with solar north at the top. If the -u flag is not set the image will be centered and rotated to make solar north at the top. If CROTA2 is near 180 degrees (within 0.1 degrees) the roll will be done as a flip about X and a flip about Y and the centering will be to the nearest pixel. If -u is not set OR if -r is set the image will be remapped with full centering and rotation. -u set takes precendence over -r. if both u=0 and r=0 then the image will be flip-flipped if CROTA2 is within 1 degree of 180. The default for 'r' is set, so if you want to get the normal HMI image with solar north up without interpolation or sub-pixel centering, call without -u but with r=0 (to override default r=1).

-c: Crop image. This flag will casue the image to be cropped at pixel radius RSUN_OBS/CDELT1 about CRPIX1,CRPIX2 center.

-w: White background, the -w flag will cause missing values to be white. Else black.

-x: the -x flag is used to indicate extra resolution in the color table, i.e. 16-bits per color.

Example to generate a directory full of simple grey scaled png images, perhaps for a movie

   render_image in='hmi.M_45s_nrt[2010.06.01_TAI/5d@30m]' out=./movie scaling=minmax99 outid=# outname=M 

Example to generate a set of 4096x4096 and 1024x1024, and 256x256 pixel images of magnetograms in the current directory

using a color table the adds dynamic range to small absolute values. The times will omit the seconds field in this example.

   render_image in='hmi.M_45s_nrt'$QRY \
     outname=M \
     palette=/home/phil/apps/mag.lut \
     outid=time:13 \
     -c \
     min=-500 \
     max=500 \
     type=jpg \
     -w \
     scale=1,4,16 \
     out='| ppmlabel -color black -size {%0.75:5} -x 15 -y {%98} -text "SDO/HMI Quick-Look Magnetogram: {ID}" | pnmtojpeg -quality=95'

Bug:

Using the MAG scaling with a list of scale sizes, any instance of scale=1 must appear last in the list. This is because the values of the image data are replaced in the original array in the scale=1 case. This will affect any scaling type that modifies the values of the data.

Bug:

Does not make 16-bit colors correctly, or I can not get ppm tools with correct flags...