Command: rasdump

Syntax

rasdump { <file> }

Description

Create a screen image file.

Parameters

• <file>
  The file to be created. The parameter may be omitted when the output is directed to an external filter process (-uof).

Switches

• -bit=1|2|3|4|8|24|32
  Bits-per-pixel for the output image. 1 implies a monochrome image and is equivalent to using the -mono switch. 8 implies create the file with a maximum of 256 colors. 24 implies create the file with true color. The default value depends on the output format but is typically 8 (24 for png and jpeg).

• -bmp
  Produce output in .bmp format. Permitted image depths are 1, 8 and 24.

• -box=<screen_box>
  Four values indicating the x,y,x,y of two opposite corners of the area to be dumped. These values are screen coordinates. This switch is ignored when the -dim/dsc switch is present.

• -c
  If <file> exists, request confirmation from the user before it is overwritten.

• -ch=<channel>
  Send the output to a binary channel (opened by open -li=<port>). The output will be wrapped in an Xmarc Hose Protocol packet of type NET_PACKET_FILE_CONTENTS. It will be preceded by a packet of type NET_PACKET_MBR if the -box switch is present.

• -clp
  Do not produce a file, but copy the output to the clipboard. This option is available on Windows systems only and will force the output format to BMP. All other switches defining a format and the <file> parameter will be ignored if this switch is present.

• -dim=<nums>
  Scale the image to a different size to that of the window (-iw). <nums> is a 2-element numeric array supplying the width and height of the output image and should have the same aspect ratio as the window, which must be a graphic window. If the aspect ratios are different, the results are unpredictable.

• -dsc=<num>
  Scale the image to a different size to that of the window (-iw). <num> is a positive numeric value supplying a scaling factor to be applied to the window dimensions. The window must be a graphic window. This is an alternative to the -dim switch.
  
  Note: Use of the -dim or -dsc switch will suppress the -box, -fram, -v and -wb switches and will ensure that the dumped contents are free of any window contents currently obscuring the target window. Graphic entities on a window's overlay will be included in the resulting image.

• -frame
  When combined with the -iw switch, the window frame is included in the image. By default, or if the -box, -dim, -dsc, -full or -wb switches are used, the frame is omitted from the image.

• -full
  Use the contents of the full graphic screen.

• -gam
  Gamma correction for PNG output. If omitted, a suitable default is used.

• -gif
  Produce output in GIF format. All GIF images produced are 8-bit 256 color images.

• -gray
  Produce a grayscale image file. This is not permitted for all output formats.

• -h=<num>
  Record the number of menu options high to enable the image to be used subsequently as a menu.

• -hot=<x,y>
  The pixel position of a hotspot associated with the image. If omitted, 0,0 is assumed. The Y coordinate system of an image has 0 at the top-left corner. Note: of the supported output formats, only Xmarc images have a hotspot capability.

• -int
  Create an interlaced image file (PNG output only).

• -iw=<window>
  Use the contents of a window to create the image file. If this is omitted, the current graphic window is used.

• -jpg
  Produce output in JPEG format. The image depth is coerced to 24-bit color.

• -mono
  Create a monochrome image file (even on a color system).

• -nts
  Do not scale tile pattern bitmaps. This option may be used in conjunction with the -dim or -dsc switch which scales the output. Without this switch tiled pattern fillstyles (applied to polygon entities) are scaled along with everything else. With this option such tiled patterns are not scaled.

• -phys=<nums>
  For PNG output, supply the physical pixel dimensions as though the image were a scanned image. The dimensions indicate "dots per meter" values. One value may be supplied, applicable to both X and Y axes, or a 2-element array may be supplied indicating separate X and Y values. For non-PNG output, this option is ignored.

• -png
  Produce output in PNG format. Permitted image depths are 2, 3, 4, 8, 24, 32 for grayscale, 1 for monochrome, and 8,24,32 for color. Alpha-blended images may be created using an image depth of 32.

• -scal=<nums>
  For PNG output, supply the scale, namely what each pixel of the image represents in meters. One value may be supplied, applicable to both X and Y axes, or a 2-element array may be supplied indicating separate X and Y values. If the scale is required but unknown use -scal=0, and it will be computed automatically. For non-PNG output, this option is ignored.

• -tif
  Produce output in Tiff format. Permitted image depths are 1, 4, 8, 24,32. Alpha-blended images may be created using an image depth of 32.

• -trans
  Create a raster stencil (or alpha-blend for 32-bit PNG output) in the file to enable the image to be retrieved in transparent mode.

• -uof=<string>
  Instead of creating a file, pipe the output to a unix filter program.

• -v
  This only applies to graphic windows and will dump the contents of the virtual window (if it is a scrolling window), or the save_under if this active. Without this switch, only the currently visible contents are dumped, which may include bits of other windows which obscure the target window. This option also turns the -frame option off.
  
  Note: Graphic entities on a window's overlay are not part of a window's save_under, so such entities will not appear in the output image.

• -w=<num>
  Record the number of menu options wide to enable the image to be used subsequently as a menu.

• -wb=<points>
  Two points in modeling space defining corners of a box within window (-iw) to be used as the area to be dumped. The window must be a graphic window for this switch to be valid. This switch is ignored when the -dim/dsc switch is present.

• -wbmp
  Produce output in .wbmp format. The image depth is forced to 1.

• -z=<num>
  Compression level for some output formats:
     PNG: A Z compression level. The range is 1 through 9.
     Tiff: A compression type, 1 for LZW, 2 for RLE, 0 for none.
  If omitted, a suitable default is used.

Notes

If a window is iconized or invisible, it may only be dumped if it is a graphic window with the save-under attribute set.

If no format is specified (e.g. -bmp, -gif, -jpg, -png, -wbmp) an Xmarc format image file is created with a permitted image depth of 1, 8 or 24.

Examples

Create myfile.ras using a rubber box to indicate the dump area:

rasdump myfile.ras, -box=sbox

Dump the full contents of window 4:

rasdump myfile.ras, -iw=win4

Dump a specific area from window 2 as a JPEG:

rasdump garea.jpg, -jpg, -iw=win2, -wb=<p0,(500,500,0)>

Dump a rubber box selection to the clipboard (Windows only):

rasdump -clp, -box=sbox

Dump the full contents of window 2 as a grayscale PNG:

rasdump myfile.png, -iw=win2, -png, -gray, -bit=4

Dump the full contents of a window as a PNG with metrics:

rasdump myfile.png, -iw=mywin, -png, -phys=423622, -scal=0.005

See Also