# coyote: CGPS2RASTER

- coyote/Utilities
- coyote/Graphics
- [Source code]

Description

      The purpose of this program is to convert a PostScript file to a high
      resolution raster file, using the ImageMagick convert command to do the
      conversion. `ImageMagick  <http://www.imagemagick.org/script/index.php>` must
      be installed on your computer.
      Note that one restriction the ImageMagick convert command imposes is that it
      cannot convert encapsulated PostScript files that are in landscape mode to
      raster files. These raster files will be clipped at one end of the file. If you
      wish to do the conversion properly, make sure encapsulated landscape plots are
      in portrait mode.
      The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>`
      to be installed on your machine.

Categories

      Utilities, Graphics

Params

      ps_filename: in, required, type=string
          The name of the input PostScript file that is being converted to a raster file.
          If not provided, the user will be asked to select a file.
      raster_filename: in, required, type=string
          The name of the output raster file that is being converted from the PostScript file.
          If not provided, the output filename is created from the input PostScript file name.
          Note, this is the preferred way to create the output filename, since the OUTPUTNAME
          keyword has been depreciated as an input keyword.

Keywords

      allow_transparent: in, optional, type=boolean, default=0
          To make the background of some image files white, rather than transparent,
          you have to set the "-alpha off" string in the ImageMagick call. This
          string is automatically added to the ImageMagick call unless this keyword
          is set, in which case the string is not added and the image background will
          be transparent.
      bmp: in, optional, type=boolean, default=0
         Set this keyword to convert the PostScript output file to a BMP image. Requires ImageMagick.
      delete_ps: in, optional, type=boolean, default=0
         Setting this keyword will delete the PostScript file that is used as the intermediate
         file in the conversion to other file types.
      density: in, optional, type=integer, default=300
         The horizontal and vertical density (in dots per inch, DPI) of the image when the PostScript file
         is converted to a raster format by ImageMagick.
      filetype: in, optional, type='string', default=""
         This keyword provides a generic way of setting the `BMP`, `GIF`, `JPEG`, `PNG`, and `TIFF`
         keywords. Set this keyword to the type of file output desired, and the correct "output"
         keyword will be set.
      gif: in, optional, type=boolean, default=0
         Set this keyword to convert the PostScript output file to a GIF image. Requires ImageMagick.
      height: in, optional, type=integer
         Set this keyword to set the height of the resulting raster file in pixel units. The width of the
         raster will be such as to preserve the aspect ratio of the starting image. This keyword
         cannot be used if the `WIDTH` keyword is used at the same time.
      im_command: out, optional, type=string
         Set this keyword to a named variable to return the ImageMagick command or commands used to
         produce the desired output. If this keyword is used, the ImageMagick commands are NOT executed,
         but are simply constructed and returned to the user. If a resize is required by using either the
         `HEIGHT` or `WIDTH` keywords, then the return value is a two-element string array. Otherwise, it
         is a scalar string.
      im_options: in, optional, type=string, default=""
         A string of ImageMagick "convert" options that can be passed to the ImageMagick convert
         command. No error checking occurs with this string.
      jpeg: in, optional, type=boolean, default=0
         Set this keyword to convert the PostScript output file to a JPEG image. Requires ImageMagick.
      outfilename: out, optional, type=string
         On exit, the name of the output file that was created.
      pdf: in, optional, type=boolean, default=0
         Set this keyword to convert the PostScript output file to a PDF file. Requires Ghostscript.
      png: in, optional, type=boolean, default=0
         Set this keyword to convert the PostScript output file to a PNG image. Requires ImageMagick.
      portrait: in, optional, type=boolean, default=0
         Set this keyword to indicate the PostScript file is in portrait mode. Otherwise, landscape
         mode is assumed.
      resize: in, optional, type=integer, default=25
         If an image is being created from the PostScript file, it is often resized by some
         amount. You can use this keyword to change the value (e.g, RESIZE=80). Set this keyword
         to 0 to avoid any resizing of the output raster file.
         The value is passed on to resize argument as a percentage in the ImageMagick call.
      showcmd: in, optional, type=boolean, default=0
         Set this command to show the command used to do any PostScript coversions.
      silent: in, optional, type=boolean, default=0
         Set this keyword to suppress output from the file. Is this keyword is set, be
         sure to check the `SUCCESS` keyword on exit.
      success: out, optional, type=boolean
          On exit, this keyword is set to 1 if the program successfully managed to create a
          raster file. It will be set to 0 otherwise.
      tiff: in, optional, type=boolean, default=0
         Set this keyword to convert the PostScript output file to a TIFF image. Requires ImageMagick.
      width: in, optional, type=integer
         Set this keyword to set the resulting width of the raster file. The height of the
         raster will be such as to preserve the aspect ratio of the starting image. This keyword
         cannot be used if the `HEIGHT` keyword is used at the same time.

Examples

      To create a line plot in a PostScript file named lineplot.ps and
      also create a PNG file named lineplot.png for display in a browser,
      type these commands::
          cgPS_Open, FILENAME='lineplot.ps'
          cgPlot, Findgen(11), COLOR='navy', /NODATA, XTITLE='Time', YTITLE='Signal'
          cgPlot, Findgen(11), COLOR='indian red', /OVERPLOT
          cgPlot, Findgen(11), COLOR='olive', PSYM=2, /OVERPLOT
          cgPS_Close, /PNG

Author

      FANNING SOFTWARE CONSULTING::
          David W. Fanning
          1645 Sheely Drive
          Fort Collins, CO 80526 USA
          Phone: 970-221-0438
          E-mail: david@idlcoyote.com
          Coyote's Guide to IDL Programming: http://www.idlcoyote.com

History

      Change History::
        Written by: David W. Fanning, 12 December 2011
        Added the ability to check to see if 8-bit or 24-bit PNG files should be created. 3 April 2012. DWF.
        Modified the ImageMagick commands that resizes the image to a particular width. Necessary
           to accommodate PNG8 file output. Using ImageMagick 6.7.2-9. 4 April 2012. DWF.
        Added FILETYPE keyword. 13 October 2012. DWF.
        Apparently Macs can't handle the version number, so I have removed the version number
            check for Macs. 13 October 2012. DWF.
        Worked on getting the WIDTH keyword to work correctly with Portrait mode files. 19 February 2013. DWF.
        Added the ability to set the number of bits per channel with TIFF files with the IM_TIFF_DEPTH
            keyword in cgWindow_SetDefs, and changed the default number of bits to 8 per channel
            from the previous 16. 14 May 2013. DWF.
        I changed the way raster files are resized because the results were inconsistent in the previous version.
            I now use a second "convert" command to resize the raster file that has previously been produced. 14 Jan 2014. DWF.
        Added HEIGHT keyword to allow the height of the raster file to be set. 14 Jan 2014. DWF.
        Added IM_COMMAND keyword to return the ImageMagick command or commands used to produce the raster file. 14 Jan 2014. DWF.
        New resize algorithm was noticably slower. Went back to a single ImageMagick command, but done correctly now. 15 Jan 2014. DWF.
        Problem with WIDTH and HEIGHT keywords being reversed. Had to do with putting this calculation before ROTATE in
            ImageMagick command. Now placed in the correct order, I think. 20 Feb 2014. DWF.
        Width can be set to zero in some instances. Now handling that case to undefine WIDTH. 1 March 2014. DWF.

Copyright

      Copyright (c) 2011-2014, Fanning Software Consulting, Inc.