home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / zip / graphics / utility / mgif40.lzh / MGIF40 / MGIF.1 < prev    next >
Text File  |  1993-08-25  |  18KB  |  492 lines
  1.  
  2. NAME 
  3.     mgif - display a GIF and Degas images in monochrome 
  4.  
  5. SYNOPSIS 
  6.     mgif [ -i ] [ -v ] [ -N ] [ -pi1 | -pi2 ] file...  
  7.     mgif -fl [ -m ] file...  
  8.  
  9. DESCRIPTION 
  10.     Mgif  displays  color  GIF  and  Degas  PI1  or  PI2 images on a
  11.     monochrome ST display.  GIF files carry  the  extensions  !.gif"
  12.     and are  compressed  using  LZW  codes.  It uses Floyd-Steinberg
  13.     dithering to simulate color.   In  addition,  this  new  version
  14.     implements   !flicker"  palettes  to  simulate  grayscale  on  a
  15.     monochrome screen.  All things  considered,  it  does  a  decent
  16.     job.  
  17.  
  18.     Mgif  now  also  contains numerous image processing functions to
  19.     enhance images.  Included are: 
  20.  
  21.         Histogram equalization
  22.         Contrast stretching
  23.         Blurring
  24.         Brightening (or darkening)
  25.         Convolutions (numerous)
  26.         Enlarge/reduce
  27.         Inversion (negation with threshold)
  28.         Log scaling
  29.         Thresholding
  30.         Median filtering
  31.         Histogram plot
  32.  
  33.     Mgif allows each image processing function to be cummulative  or
  34.     each operation  can  be independent.  Mgif is interactive (not a
  35.     GEM program) and prompts for commands.  It also has online  help
  36.     and can save the !flicker" screen image to a special file (*.fl) 
  37.     for viewing.  Mgif can also view these files.  
  38.  
  39. OPTIONS 
  40.     The following command line options are recognized: 
  41.  
  42.     -i      Inquire about  the  file  but do not display it.  Output
  43.         contains information like image size, number of bits per 
  44.         pixel, and whether or not the  image  is  interlaced  or
  45.         sequential.  
  46.  
  47.     -v      Verbose output.  
  48.  
  49.     -N      Use the classic NTSC equation for computing luminescense 
  50.         from RGB values, that is: 
  51.  
  52.             lum = 0.299 R + 0.587 G + 0.114 B 
  53.  
  54.         Otherwise the  values  are unweighted.  This option only
  55.         makes sense for files with color maps in which the entry 
  56.         for each color uses different values for red, green, and 
  57.         blue.  It is not recommended to use  this  for  existing
  58.         grayscale images.    Note  that the actual equation used
  59.         is: 
  60.  
  61.             lum = (30 R + 59 G + 11 B) / 100 
  62.  
  63.         which is close enough.  Also note that NTSC luminescense 
  64.         is a global option and must be set on program entry.  
  65.  
  66.     -pi1    Files specified are Degas  PI1  files  rather  than  GIF
  67.         files, i.e.  low resolution 320x200 16 color images.  
  68.  
  69.     -pi2    Files  specified  are  Degas  PI2  files rather than GIF
  70.         files, i.e.  medium resolution 640x200 4  color  images.
  71.         You  will  have  to either shrink the horizontal axis or
  72.         expand the vertical axis after each image is read  since
  73.         the aspect  ratio  is  wrong.    Since some images react
  74.         better to shrinking than expanding, the choice  is  left
  75.         to the  user.    It  helps  to  blur  the  image  first,
  76.         especially  when  shrinking,  since  there  are  only  4
  77.         intensities to  start  with.  Blurring will increase the
  78.         number of intensities  and  shrinking  will  reduce  the
  79.         effect of the blur.  This is generally optimal for these 
  80.         images.  
  81.  
  82.     file    One or more GIF files (or Degas files if -pi1 or -pi2 is 
  83.         specified).  
  84.  
  85.     Mgif can  also  be  used as a simple flicker file viewer.  To do
  86.     so, you must specify the -fl option.   Only  the  -m  option  is
  87.     recognized in this case: 
  88.  
  89.     -fl     Just display  flicker  files  (*.fl).    With  no  other
  90.         options, each file is displayed sequentially.   Any  key
  91.         entered  goes  to  the  next  file  if  there are any or
  92.         quits.  
  93.  
  94.     -m      This optional flag will attempt to create  a  mosaic  of
  95.         multiple files.    Either  two 320x400, four 320x200, or
  96.         six 200x200 images are displayed at the same time.    If
  97.         images are smaller or larger than these sizes, tile to a 
  98.         size that  fits.  For example two 320x300 images will be
  99.         tiled as if they are 320x400.  
  100.  
  101.     file    In this case, file is one or more .fl files.  
  102.  
  103. INTERACTIVE COMMANDS 
  104.     The following commands are available at the prompt: 
  105.  
  106.     Control Commands 
  107.  
  108.     ?       help 
  109.  
  110.         Clears  the  screen  and  prints  a  brief  summary   of
  111.         commands.  
  112.  
  113.     q       quit (next image) 
  114.  
  115.         Quit does  not  exit  the program.  It just moves to the
  116.         next image from the command line.  
  117.  
  118.     ESC     exit program 
  119.         Cleans up and exits the program.  
  120.  
  121.     SPACE   draw image 
  122.  
  123.         The current image, either original or new, is drawn  (or
  124.         redrawn).  
  125.  
  126.     w       what 
  127.  
  128.         Display information about the image.  
  129.  
  130.     hi      histogram 
  131.  
  132.         Plots  the  histogram  of  the  original  or  new image,
  133.         depending on which mode is toggled.   The  histogram  is
  134.         based on  intensity only.  Older versions of the program
  135.         displayed RGB histograms  as  well.    That  option  was
  136.         dropped, though it was sometimes useful.  Note that if o 
  137.         is toggled for original image, you should toggle o again 
  138.         to  plot a histogram of a transformed image, then toggle
  139.         back to work on the original.  
  140.  
  141.     o       original/new image 
  142.  
  143.         This   toggles   two   sorts   of   behavior:   1)   all
  144.         transformations take place on the original image and are 
  145.         not  cummulative,  2)  all transformations take place on
  146.         the new (last) image and are cummulative.  
  147.  
  148.     f       file operations 
  149.  
  150.         Currently, the only file operation is to save  the  last
  151.         screen  image to a special file having a !.fl" suffix, a
  152.         so called !flicker" file.  This file contains the  three
  153.         screen  images  which are used by the flicker routine to
  154.         simulate grayscale.    These  are  the   actual   screen
  155.         bitmaps, truncated  to the actual image size.  Note that
  156.         in order to save an image in this format, you must first 
  157.         display it completely  by  the  flicker  routine.    You
  158.         should  not  escape  the  actual  screen draw but let it
  159.         finish.  
  160.  
  161.     cp      image copy 
  162.  
  163.         You can copy the new, transformed image to the  original
  164.         and visa versa.  The former is the most useful.  
  165.  
  166.  
  167.     Display Options 
  168.  
  169.     n       noise 
  170.  
  171.         Adds noise not to the image but to the !flicker" process 
  172.         itself.   Can  help  in  images  which  have  artificial
  173.         banding as a result of the dithering process.   You  are
  174.         asked   for  a  value,  which  if  0,  turns  off  noise
  175.         addition.  Otherwise, it is a  percentage  (0  to  100).
  176.         Each time o is toggled, noise is reset to 0 (i.e. off).  
  177.  
  178.     g       Laplace filter 
  179.  
  180.         This, like noise, is not applied to the image itself but 
  181.         rather in  the flicker process.  It helps to define hard
  182.         edges in images and implements  a  Laplace  filter.    A
  183.         quantity, Beta,  is required.  Use integers (1, 2, etc.)
  184.         for this value.  A value of 1  corresponds  to  Beta  of
  185.         0.25, a  value of 2 corresponds to Beta of 0.50, etc.  A
  186.         value of 0 turns off Laplace filtering.  Each time o  is
  187.         toggled,  Beta  is  reset  to  0 (i.e. Laplace filtering
  188.         off).  
  189.  
  190.  
  191.     Frame Processes 
  192.  
  193.     e       enlarge 
  194.  
  195.         Enlarges images by  2x  (only).    You  can  choose  the
  196.         dimension  to enlarge as either horizontal, vertical, or
  197.         both.  Note that if the size of an image  is  such  that
  198.         enlarging  it will exceed the amount of memory allocated
  199.         for the image, the enlarge is  aborted.    The  enlarged
  200.         image can be larger than the screen, but must fit in the 
  201.         raster memory.   Enlarging is done by shifing pixels and
  202.         filling in the holes within a scan line with the average 
  203.         of adjacent pixels, and between scan lines by  averaging
  204.         adjacent scan lines to create the new one.  
  205.  
  206.     s       shrink 
  207.  
  208.         Reduces images  by  2x  (only).  Makes them half size in
  209.         height and width.   You  can  choose  the  dimension  to
  210.         reduce   as   either   horizontal,  vertical,  or  both.
  211.         Reduction is a simple decimation which throws away every 
  212.         other point in a scan line and every other scan line.  
  213.  
  214.     z       zoom 
  215.  
  216.         The image is drawn (without flicker) then gridded with a 
  217.         20x20 grid, then a box  appears  representing  the  zoom
  218.         window  which is always half the height and width of the
  219.         image.  Move  the  box  with  the  arrow   keys.      By
  220.         themselves,   the  arrow  keys  move  8  pixels  in  the
  221.         corresponding direction.  Shifted arrows move the box  1
  222.         pixel at  a  time.    Detect the final location with the
  223.         INSERT key.  Any other  key  cancels.    Once  the  zoom
  224.         rectangle  is  defined, the image defined is expanded to
  225.         fit the current image size (similar to enlarge with both 
  226.         directions specified).  
  227.  
  228.     cu      cut 
  229.  
  230.         Cuts out a rectangular area of the image  for  scrutiny.
  231.         You can choose to cut areas which are partially or fully 
  232.         out of   the   display   area.    First,  the  image  is
  233.         redisplayed without flicker.  Then a 20x20 pixel grid is 
  234.         overlaid.  A crosshair system is then drawn.   Move  the
  235.         crosshairs  with  the  arrow  keys  (see  zoom section).
  236.         Detect the upper left corner first with the INSERT  key.
  237.         Then do  the  same  for the lower right corner.  The cut
  238.         image is drawn with the same size as the cut area  which
  239.         can then  be  enlarged  if desired.  Use zoom to cut and
  240.         enlarge (with restrictions) all at  once.    Cutting  is
  241.         helpful for a number of uses including: 1) zooming in on 
  242.         a  smaller portion, 2) to trim artificial borders around
  243.         an image, 3) for artistic cropping.  
  244.  
  245.     r       rotate 
  246.  
  247.         You can only rotate the original image in this  version.
  248.         If  you  are in !new" mode, you are asked if you want to
  249.         proceed (because any transformations  done  in  the  new
  250.         buffer  will  be  lost) and if you answer !yes", you are
  251.         placed in  orig  mode  where  the  transformation  takes
  252.         place.   You are asked for an angle which must be either
  253.         -90 (for 90  degree  clockwise  rotation),  90  (for  90
  254.         degree counter  clockwise  rotation)  or 180.  After the
  255.         image is rotated, you are placed in !new" mode where all 
  256.         suggessive transformations  accumulate.    The  original
  257.         image, however, is also rotated.  
  258.  
  259.     mi      mirror 
  260.  
  261.         You  can  mirror  about a horizontal axis (top to bottom
  262.         swap) or a vertical axis (left to right swap).  
  263.  
  264.  
  265.     Point Processes 
  266.  
  267.     he      histogram equalization 
  268.  
  269.         Histogram equalization attempts  to  smooth  out  images
  270.         with skewed  or  narrow  histograms.    A histogram is a
  271.         graph showing the relative number of  pixels  with  each
  272.         possible intensity  value.  The practical use is to make
  273.         images more uniform in contrast by making the  histogram
  274.         more  uniform  and hence representing all intensities as
  275.         equally as possible.  It is often not possible to achive 
  276.         a very smooth histogram, but more often than not  it  is
  277.         possible to    improve   image   quality.      Histogram
  278.         equalization can also help to bring out structure hidden 
  279.         in shadow.  The technique used here  does  not  randomly
  280.         redistribute pixels  to  new  intensity levels.  It just
  281.         changes the intensity  of  all  pixels  with  a  certain
  282.         intensity,  thus  stretching  the histogram so that each
  283.         intensity is represented uniformly.  
  284.  
  285.     i       inverse (negation) 
  286.  
  287.         Invert an image, i.e.  make low intensity pixels  bright
  288.         and visa  versa.    Inversion  is  implemented here more
  289.         generally.  A threshold is needed.   If  it  is  0,  the
  290.         entire image  is  inverted.    If it is a negative value
  291.         between 0 and -255, only pixels  below  that  level  are
  292.         inverted.   If it is a positive value between 0 and 255,
  293.         only pixels above that level are inverted.  
  294.  
  295.         The basic algorithm is: 
  296.  
  297.             For threshold = 0:
  298.         
  299.                 new[i] = 255 - old[i]
  300.         
  301.             For threshold < 0:
  302.         
  303.                 new[i] = 255 - old[i], old[i] < -threshold
  304.                        = old[i], otherwise
  305.         
  306.             For threshold > 0:
  307.         
  308.                 new[i] = 255 - old[i], old[i] > threshold
  309.                        = old[i], otherwise
  310.  
  311.     l       log scaling 
  312.  
  313.         Application of log scaling helps some images.  Here each 
  314.         pixel's value is scaled to the ratio of the logarithm of 
  315.         the pixel's intensity and the maximum intensity  in  the
  316.         image.  
  317.  
  318.         The basic algorithm is: 
  319.  
  320.             new[i] = maxval * log(old[i]) / log(maxval)
  321.         
  322.             maxval is highest intensity in the image
  323.  
  324.     t       threshold (black & white) 
  325.  
  326.         This  process  makes  all pixels above a given threshold
  327.         intensity white and all below the threshold black.    It
  328.         is useful in producing line art.  
  329.  
  330.         The basic algorithm is: 
  331.  
  332.             new[i] = 255, if old[i] > threshold
  333.                    =   0, if old[i] <= threshold
  334.  
  335.     co      contrast expansion 
  336.  
  337.         Attempts to expand the contrast of an image to cover the 
  338.         entire range  of  256  allowable  grayscales.   Somewhat
  339.         similar  to  histogram  equalization  but  it  does  not
  340.         redistribute actual   pixels.    You  are  asked  for  a
  341.         threshold which is a pixel count.  This  determines  the
  342.         lowest  and highest intensities, based on the histogram,
  343.         which define the range to be stretched.  What happens is 
  344.         that the histogram is searched beginning at the low  end
  345.         for  the first intensity level with more pixels than the
  346.         input threshold.  This is also done starting at the high 
  347.         end.  A range is thus defined.  Entering 0 will define a 
  348.         range starting with the lowest (and  highest)  intensity
  349.         for which there are more than one points.  
  350.  
  351.         The basic algorithm is: 
  352.  
  353.             new[i] = 255 * (old[i] - lo) / (hi - lo)
  354.         
  355.             where lo to hi is new contrast range
  356.  
  357.         The contrast range is defined by the intensities of bins 
  358.         which exceed the given threshold pixel count at both low 
  359.         and high ends of the histogram.  
  360.  
  361.     br      brighten (or darken) 
  362.  
  363.         Here  a constant intensity is added (or subtracted) from
  364.         every pixel.  A negative number causes  image  darkening
  365.         and a  positive number causes image brightening.  Pixels
  366.         which would otherwise go less than 0 or greater than 255 
  367.         are limited to these values, respectively.  
  368.  
  369.         The basic algorithm is: 
  370.  
  371.             new[i] = old[i] + constant
  372.  
  373.  
  374.     Area Processes 
  375.  
  376.     bl      blur 
  377.  
  378.         Blurring an image can also help contrast, though at  the
  379.         expense of  loss  of detail.  Here a 3x3 neighborhood is
  380.         used.  Often in practice a 5x5 neighborhood is used, but 
  381.         that tends to take a relatively long time.  
  382.  
  383.         The  basic  algorithm  is  (j  runs  through   the   3x3
  384.         neighborhood): 
  385.  
  386.             new[i] = sum (old[i] ) / 9
  387.                         j       j
  388.  
  389.     me      median filter 
  390.  
  391.         Median filtering can remove noise from an image.  Here a 
  392.         3x3  neighborhood  is used with the median value of each
  393.         of the 9 pixels replacing the pixel of interest.    This
  394.         is  done in place so that the next pixel examined within
  395.         the  row  or  the  next  row  will  see  pixels  already
  396.         filtered.  
  397.  
  398.         The   basic   algorithm  is  (j  runs  through  the  3x3
  399.         neighborhood): 
  400.  
  401.             new[i] = median (old[i] )
  402.                            j       j
  403.  
  404.     v       convolution filters  
  405.  
  406.         Apply one of a number of 3x3 convolutions to  an  image.
  407.         Choose  one of the built-in filters (number greater than
  408.         0) or enter 0 for user defined.  In the latter case, you 
  409.         enter the 9 elements of  the  convolution  kernel  along
  410.         with  a flag if there will be a multiplier (or divisor).
  411.         Then enter that scaling factor.  All quantities  are  to
  412.         be integers.  
  413.  
  414.         The   basic   algorithm  is  (j  runs  through  the  3x3
  415.         neighborhood): 
  416.  
  417.             new[i] = sum (old[i]  * k )
  418.                     j       j    j
  419.         or
  420.         
  421.             new[i] = sum (old[i]  * k ) * multiplier
  422.                     j       j    j
  423.         or
  424.         
  425.             new[i] = sum (old[i]  * k ) / divisor
  426.                     j       j    j
  427.         
  428.             where k  is the corresponding kernel value.
  429.                    j
  430.  
  431.         It is not  a  matrix  multiply,  rather  an  element  by
  432.         element multiply and summation.  
  433.  
  434. FILES 
  435.     *.gif   GIF image files
  436.     *.pi1   Degas low resolution files
  437.     *.pi2   Degas medium resolution files
  438.     *.fl    flicker files
  439.  
  440. SEE ALSO 
  441.     gif(5), showfl(1L), pi1(1L) 
  442.     Gonzalez and Wintz, Digital Image Processing.  
  443.     Lindley, Practical Image Processing In C.  
  444.     Burger and Gillies, Interactive Computer Graphics.  
  445.  
  446. DIAGNOSTICS 
  447.     Various warnings  attempting  to  isolate  corrupted files.  The
  448.     usual messages about errors openning files, etc.   If  an  error
  449.     occurs  during  a  processing  function,  the  prompt  line will
  450.     indicate the error.  
  451.  
  452. NOTES 
  453.     Source code has standalone versions (i.e.  single  entry  point)
  454.     for both reading GIF files and displaying grayscale bitmaps with 
  455.     flicker.  
  456.  
  457. BUGS 
  458.     As  compiled,  mgif handles images up to 400,000 pixels or about
  459.     640x620 (or any other combination totaling less  than  400,000).
  460.     It  needs  dynamic  memory but I generally stay away from GEMDOS
  461.     Malloc(2), prefering  libc  malloc(3)  (i.e.  off  stack  in  my
  462.     library).  
  463.  
  464.     GIF decoding  is  slow  and  could  be faster.  Some of the area
  465.     processes (blur, etc.) could also be faster.  
  466.  
  467.     Log scaling needs logarithms but I did not want to use  floating
  468.     point so I get a crude (two significant digit) base 2 log.  
  469.  
  470.     The flicker file (*.fl) format is not fully defined.  
  471.  
  472. TODO 
  473.     Though  mgif  is now fairly complete, there are some things that
  474.     would be nice to add.  Here is the short list: 
  475.  
  476.         * Merge images
  477.     
  478.         * Batch processing
  479.     
  480.         * Save history of changes for batch
  481.     
  482.         * Histograms by pixel range directly
  483.     
  484.         * Comparative flicker (i.e. A/B)
  485.  
  486. AUTHOR 
  487.     Bill Rosenkranz (rosenkra@convex.com) 
  488.     Flicker adopted from code by Klaus Pedersen (micro@imada.dk) 
  489.  
  490. VERSION 
  491.     mgif 3.5 91/6/15 rosenkra 
  492.