hiExportImage
hiExportImage(
?fileName t_filename
[?window w_window]
[?exportRegion s_exportRegion]
[?bBox l_bBox]
[?width n_width]
[?height n_height]
[?scaleFactor n_scaleFactor]
[?haloType s_haloType]
[?scaleHalos g_scaleHalos]
[?fileType g_fileType]
[?keepAspect g_keepAspect]
[?transparentBG g_transparentBG]
[?colorType s_colorType]
[?fgColor t_fgColor]
[?bgColor t_bgColor]
[?verbose g_verbose]
[?windowProps g_windowProps]
[?decorations g_decorations]
)
=> t / nil
Description
Takes a screen capture of a design in a graphics window and exports it to a standard image format such as PNG. This function can only be used with graphics windows.
With this function, you can take a screen capture of the part of the design that is currently visible in the window, the entire design, or a specific region. You can specify the size of the resulting image, either by specifying a scaling factor or a custom size. This function maintains the aspect ratio of the original image.
You can also choose a background color for the image or specify a transparent background.
Screen captures taken with this function will also capture halos. You can adjust halos with the ?haloType and ?scaleHalos arguments.
You can save images in any of the formats supported by Qt: BMP, JPG, PNG, PPM, XBM, and XPM. To specify the format, use the appropriate suffix with the filename. Note, however, that PNG is the recommended format; not all features are supported by the other formats.
The shadow mode—in which unselected objects are dimmed and selected objects are displayed at full brightness in their original layer color instead of the selection color—is ignored by the export image functions. Objects are displayed in their normal colors and brightness in the exported image.
Arguments
|
?fileName t_filename
|
|
|
The name of the file (or path) in which to save the exported image. The file name can contain any filesystem character.
The suffix of the file determines the image format. For example, if you specify myfile.png, the image get saved as a PNG file. All formats supported by Qt are supported; currently, these are: BMP, JPEG, PNG, PPM, XBM, and XPM. Note, however, that PNG is the recommended format; not all features are supported by the other formats.
|
|
?window w_window
|
The window ID of the graphics window containing the design to export. You can get the window ID with the hiIsWindowSpecifier function. You can also specify window(n) where n is the window number.
Default value: the current window
|
|
?exportRegion s_exportRegion
|
|
|
The area of the design to capture. Specify one of the following symbols:
’visibleArea: The area of the design that is currently visible in the specified window
’entireDesign: The entire design, not just the part that is currently visible in the window
’selectedArea: The area selected by the user; see the description of the ?bBox argument.
If the l_bBox argument is specified (and it is a valid bounding box), s_exportRegion is automatically set to ’selectedArea.
Default value: ’visibleArea
|
|
?bBox l_bBox
|
The screen coordinates of the area to capture, specified as a list of lower-left and upper-right coordinates (assuming 0:0 to be the lower-left corner of the screen):
list(x1:y1 x2:y2)
where x1 is the lower-left x coordinate, y1 is the lower-left y coordinate, x2 is the upper-right x coordinate and y2 is the upper-right y coordinate.
To provide the user the ability to interactively select the region to capture, you can specify enterBox() as the value of this argument. The user can then select the area to capture by clicking-and-dragging the mouse.
If a valid bounding box is specified for this argument, the s_exportRegion argument is automatically set to ’selectedArea.
|
|
?width n_width
|
The desired width of the image, specified in pixels.
Default value: 0
You can specify either the width or the height, or both. If you specify only the width or only the height (and the other value is 0 or unspecified), then the other value is calculated automatically according to the aspect ratio of the region being captured.
If you specify both the width and height, then they are taken to be the maximum values. In order to maintain the aspect ratio of the original region, either the width or height might be reduced; the resulting image is never larger than the width and height specified. For example, if you specify a width of 400 and a height of 400, and the area being captured is not as high as it is wide, then the resulting image is of 400 pixels wide but less than 400 pixels high to maintain the aspect ratio.
If both width and height are 0, the image remains the same size as the region being captured.
If you specify both n_scaleFactor and either n_width or n_height, n_scaleFactor is used.
|
|
?height n_height
|
The desired height of the image, specified in pixels.
Default value: 0
You can specify either the width or the height, or both. If you specify only the width or only the height (and the other value is 0 or unspecified), then the other value is calculated automatically according to the aspect ratio of the region being captured.
If you specify both the width and height, then they are taken to be the maximum values. In order to maintain the aspect ratio of the original region, either the width or height might be reduced; the resulting image is never larger than the width and height specified. For example, if you specify a width of 400 and a height of 400, and the area being captured is not as high as it is wide, then the resulting image is of 400 pixels wide but less than 400 pixels high to maintain the aspect ratio.
If both width and height are 0, the image remains the same size as the region being captured.
If you specify both n_scaleFactor and either n_width or n_height, n_scaleFactor is used.
|
|
?scaleFactor n_scaleFactor
|
|
|
The factor by which to scale the image. A number greater than 1.0 scales the image up; a number less than 1.0 scales it down. For example, a factor of 2.0 doubles the size of the image while a factor of 0.5 reduces its size by half.
Default value: 1.0
An image requires <width>*<height>*<scaleFactor>*32 bits of memory, therefore scaling an image to a high factor can cause an out of memory condition. If insufficent memory to save an image is an issue, a warning message is displayed advising that you scale down the image size before attempting to save it again.
If you specify both n_scaleFactor and either n_width or n_height, n_scaleFactor is used.
|
|
?haloType s_haloType
|
|
|
One of the following symbols:
’default
’simple
specifying whether halos should be rendered as they appear on the screen (’default) or in a single translucent color (’simple). Simple halos typically look better than the fuzzy default halos when the image is printed.
Default value: ’default
|
|
?scaleHalos g_scaleHalos
|
|
|
t or nil. Specifies whether to scale halos relative to the size of the image you capture. By default, halos are a constant size, regardless of whether you zoom in or out of the design, and can look too small or too large in the resulting image.
Default value: nil
|
|
?fileType g_fileType
|
|
|
Can be set as one of the supported formats mentioned in the Description section above. This option is not required unless you are using a non-standard file suffix, as it should be deduced automatically.
Default value: ""
|
|
?keepAspect g_keepAspect
|
|
|
Set to keep the aspect ratio of the original export area, adjusting the size constraints specified by ?width and ?height accordingly. By default, if you specify width and height, this generates the exact image size that you specify, with padding if the area being exported does not match the aspect ratio of the image (for example, padding on the sides if you export to a square image from a tall rectangular canvas). If set to 't', it adjusts the size so that no padding is used.
Default value: nil
|
|
?transparentBG g_transparentBG
|
|
|
The color to use for the background color (for a transparent background, use the s_bgType argument). You can specify the color as color name strings (for example, "red") or RGB values (for example, "#ff0000").
Default: Black
If you specify this argument, s_bgType is automatically set to ’solid.
|
|
?colorType s_colorType
|
|
|
Set the type of image to export. This can be one of the following symbols:
-
'fullColor(default): generate image using the colors visible on-screen. -
'monochrome: generate a monochrome image, with colors being interpolated between ?fgColor and ?bgColor. For example, if ?fgColor is black and ?bgColor is white, this generates a grayscale image with a white background and black-gray shapes. Conversely, ?bgColor black and ?fgColor black generates a grayscale image with a black background and white-gray shapes. There are no restrictions on color. -
'biColor: generate a bicolor image, with ?bgColor as the background color, and all other shapes rendered in ?fgColor. For example, ?bgColor white ?fgColor black produces a white background with black shapes.
|
|
?fgColor t_fgColor
|
The color to use as the foreground color for bicolor and monochrome exports.
Default value: ""
|
|
?bgColor t_bgColor
|
The color to use as the background color for bicolor and monochrome exports.
Default value: ""
|
|
?verbose g_verbose
|
Set to print the name of the file which was saved to the CIW.
Default value: nil
|
|
?windowProps g_windowProps
|
|
|
A list of list of key-value pairs which represent window properties, and their values, to be set before export, and restored afterwards. It is used by the thumbnailing process to perform actions such as hiding the grid, but any window property is valid. For example:
?windowProps list( list("drawAxesOn" nil) list("drawGridOn" nil)
Set the 'drawAxesOn' and 'drawGridOn' properties on the window to 'nil', and restore the original values immediately after export.
Default value: nil
|
|
?decorations g_decorations
|
|
|
A list of "decorations" to be rendered on a resulting image. Can be used to generate 'PCell' text on pcell thumbnails. It is a DPL that consists of key-value pairs indicating what to draw and where to draw it. Currently, only text is supported. For example:
?decorations ncons( '( nil text "Pcell" corner "bottomLeft"))
Will render 'PCell' in the bottom left. corner can be one of "bottomLeft", "bottomRight", "topLeft", "topRight".
Default value: nil
|
Values Returned
|
t
|
Returns t when the image file is saved.
|
|
nil
|
The window specified is not a valid window or there is another error.
|
Examples
Prompts the user to enter a bounding box, and when done, scales the selected region by 5, scales halos, and saves the image in PNG format in a file named a.png.
hiExportImage( ?fileName "a.png" ?bBox enterBox() ?scaleFactor 5 ?scaleHalos t)
Creates an image of the visible area of the design, with a transparent background and a width of 10,000 pixels wide (and the height required to maintain the aspect ratio), and saves it to a file named a.png.
hiExportImage( ?fileName "a.png" ?bgType ’transparent ?width 10000)
Creates an image of the entire design, regardless of the current zoom level, with a red background and a width of 10,000 pixels (and the height required to maintain the aspect ratio), and saves it to a file named a.png.
hiExportImage( ?fileName "a.png" ?exportRegion ’entireDesign ?width 10000 ?bgColor "red")
Creates a 10,000-pixel-wide image of the entire design, with a transparent background and simple halos, and saves it in PNG format in a file named a.png.
hiExportImage( ?fileName "a.png" ?bgType ’transparent ?exportRegion ’entireDesign ?haloType ’simple ?width 10000)
Related Topics
Screen Capture Functions
hiExportImageDialog
hiWindowSaveImage
Return to top
