NCL Home > Documentation > Graphics > Resources

Workstation, DocumentWorkstation, ImageWorkstation, NcgmWorkstation, PDFWorkstation, PSWorkstation, WindowWorkstation (wk) Resources

These resources are used to control the behavior of the various workstation classes.

Workstation is the parent class of all other workstations, and as such, resources belonging to it are applicable to all workstations, unless otherwise noted.

DocumentWorkstation workstations are used to generate pdf, postscript, encapsulated-postscript (eps) and scalable vector graphics (svg) ouput formats; These correspond respectively to "pdf", "ps", "eps", "svg" workstation types in calls to gsn_open_wks.

The ImageWorkstation class is for writing PNG output files ("png" in gsn_open_wks()).

WindowWorkstation draws to a window on the screen ("x11" in gsn_open_wks()). NcgmWorkstation generates the NCAR Computer Graphics Metafile format ("ncgm" in gsn_open_wks()).

PSWorkstation and PDFWorkstation are the original postscript and PDF workstations, respectively. They have been deprecated in favor of the DocumentWorkstation workstation, but still may be accessed by using types "oldps" or "oldpdf" in calls to gsn_open_wks. Note that the type "epsi" used with gsn_open_wks() always invokes an instance of the PDFWorkstation.

wkAntiAlias (Workstation)

Used to control whether the Workstation employs anti-aliasing algorithms in the generation of graphical output. (Anti-aliasing refers to a number of techniques for softening the appearance of graphical artifacts such as jagged edges/lines.) There are three possible settings:

On: Anti-aliasing measures are applied to all graphical output.
Off: No anti-aliasing algorithms are used.
TextOnly: Anti-aliasing is applied to only the generation of textual graphics.

NOTE: This resource is not applicable to the PSWorkstation or PDFWorkstation types.

Default: On

wkBackgroundColor (Workstation)

This resource can be a one-dimensional array containing three elements of type NhlTFloat that specify (in order) the red, green, and blue components (an RGB triplet) of the Workstation background color, or a string containing a color name from the file $NCARG_ROOT/lib/ncarg/database/rgb.txt. You may set wkBackgroundColor only when the Workstation object is created. The background color is accessed for drawing purposes using HLU color index 0 (or the defined constant NhlBACKGROUND when using the C language interface). If defining this resource with an RGB triplet, each element must be in the range 0.0 through 1.0 inclusive. If any element is invalid, the Workstation object issues a warning, and reverts to the default background color value.

Default: (0.0, 0.0, 0.0) (Black)

wkBackgroundOpacityF (Workstation)

Sets the opacity of the background color. This should be a value between 0.0 (fully transparent) and 1.0 (fully opaque).

NOTE: This resource is not applicable to the PSWorkstation or PDFWorkstation types.

Default: 1.0

wkColorMapLen (Workstation)

This read-only resource allows you to determine the number of elements currently in the wkColorMap without retrieving the whole table. This is one more than the largest currently defined index.

Default: <dynamic>

wkColorMap (Workstation)

Use this resource to set or retrieve the colormap for a Workstation object. To set this resource, use a two-dimensional array of type NhlTFloat, an array of color specification formats, or a pre-defined colormap name. If you retrieve this resource, it will be a two-dimensional array of type NhlTFloat.

For a two-dimensional array, the fastest varying dimension contains three elements that define (in order) the red, green, and blue components of a single color. Each component should be within the range 0.0 through 1.0 inclusive. If the red component of a color is specified with a negative number, then the color is considered to be a missing value, and that index of the colormap will default. In all other cases, an error message will be generated if values are outside the range of 0.0 through 1.0 inclusive.

For an array of color specification formats, each element must be enclosed in double quotes and be either an RGB triplet as described above, or a named color from the $NCARG_ROOT/lib/ncarg/database/rgb.txt file.

For a pre-defined colormap name, set the resource to one of over 40 pre-defined colormap names found in the color table gallery.

If you do not set wkColorMap, the Workstation object will use a default color map. The first triple of the wkColorMap array (index 1 of the slow-varying dimension using the Fortran interface, or index 0 using the C interface) is the background color for the Workstation and is accessed as HLU color index 0. In the default colormap, the color is dynamically determined based on the Workstation subclass. For example, the background color for the XWorkstation is black, but the background color for the PSWorkstation and PDFWorkstation is white. The background color can also be set using the wkBackgroundColor resource as a convenience.

The second triple of the wkColorMap array (index 2 of the slow-varying dimension using the Fortran interface, or index 1 using the C interface) is the foreground color for the Workstation and is accessed as HLU color index 1. The foreground color is also dynamically determined. It defaults to either white or black, whichever is determined to contrast more with the background color.

Default: "default"

wkColorModel (PDFWorkstation)

Note: applies only to the original PDF driver, referred to as "oldpdf" in gsn_open_wks.

This resource specifies the color model used to describe colors in the output PDF file. The choices are "rgb" for the Red-Green-Blue color model or "cmyk" for the Cyan-Magenta-Yellow-Black color model. Note that this resource affects the output file only. Elements of the wkColorMap array be set using the RGB model or named colors only.

Default: "rgb"

wkColorModel (PSWorkstation)

Note: applies only to the original postscript driver, referred to as "oldps" in gsn_open_wks.

This resource specifies the color model used to describe colors in the output PostScript file. The choices are "rgb" for the Red-Green-Blue color model or "cmyk" for the Cyan-Magenta-Yellow-Black color model. Note that this resource affects the output file only. Elements of the wkColorMap array be set using the RGB model or named colors only.

Default: "rgb"

wkDashTableLength (Workstation)

This read-only resource contains the number of currently available unique dash patterns.

Default: <dynamic>

wkDefGraphicStyleId (Workstation)

This read-only resource contains the default GraphicStyle object that is created along with the Workstation itself. If you call an immediate mode graphics primitive function without specifying an explicit GraphicStyle object, the Workstation uses the default GraphicStyle object to determine the attributes used to render the graphics primitive. You may modify these attributes by retrieving the default GraphicStyle object, and then setting its resources as desired.

Default: <dynamic>

wkDeviceLowerX (DocumentWorkstation)

Defines the Lower X value of the normalized device coordinate viewport on the page. It is specified in PostScript coordinate space where one unit corresponds to 1/72 of an inch. 0 addresses the left side of an 8.5" x 11" page, and 612 addresses the right side. For details on using the PostScript workstation positioning resources, see the appropriate section in the NCAR GKS User's Guide for NCAR GKS-0A Graphics. It is particularly important to consult the section in the GKS manual on using the full page if you are using the PostScript workstation positioning resources with a PostScript landscape workstation.

Default: 36

wkDeviceLowerX (PDFWorkstation)

Defines the Lower X value of the normalized device coordinate viewport on the page. It is specified in PDF coordinate space where one unit corresponds to 1/72 of an inch. 0 addresses the left side of an 8.5" x 11" page, and 612 addresses the right side. For details on using the PDF workstation positioning resources, see the appropriate section in the NCAR GKS User's Guide for NCAR GKS-0A Graphics. It is particularly important to consult the section in the GKS manual on using the full page if you are using the PDF workstation positioning resources with a PDF landscape workstation.

Default: 36

wkDeviceLowerX (PSWorkstation)

Default: 36

wkDeviceLowerY (DocumentWorkstation)

Defines the Lower Y value of the normalized device coordinate viewport on the page. It is specified in PostScript coordinate space where one unit corresponds to 1/72 of an inch. 0 addresses the bottom side of an 8.5" x 11" page, and 792 addresses the top side.

Default: 126

wkDeviceLowerY (PDFWorkstation)

Defines the Lower Y value of the normalized device coordinate viewport on the page. It is specified in PDF coordinate space where one unit corresponds to 1/72 of an inch. 0 addresses the bottom side of an 8.5" x 11" page, and 792 addresses the top side.

Default: 126

wkDeviceLowerY (PSWorkstation)

Default: 126

wkDeviceUpperX (DocumentWorkstation)

Defines the Upper X value of the normalized device coordinate viewport on the page. It is specified in PostScript coordinate space where one unit corresponds to 1/72 of an inch. 0 addresses the left side of an 8.5" x 11" page, and 612 addresses the right side.

Default: calculated as paper_width - 36, see wkPaperSize

wkDeviceUpperX (PDFWorkstation)

Defines the Upper X value of the normalized device coordinate viewport on the page. It is specified in PDF coordinate space where one unit corresponds to 1/72 of an inch. 0 addresses the left side of an 8.5" x 11" page, and 612 addresses the right side.

Default: calculated as paper_width - 36, see wkPaperSize

wkDeviceUpperX (PSWorkstation)

Default: calculated as paper_width - 36, see wkPaperSize

wkDeviceUpperY (DocumentWorkstation)

Defines the Upper Y value of the normalized device coordinate viewport on the page. It is specified in PostScript coordinate space where one unit corresponds to 1/72 of an inch. 0 addresses the bottom side of an 8.5" x 11" page, and 792 addresses the top side.

Default: calculated as paper_height - 126, see wkPaperSize

wkDeviceUpperY (PDFWorkstation)

Defines the Upper Y value of the normalized device coordinate viewport on the page. It is specified in PDF coordinate space where one unit corresponds to 1/72 of an inch. 0 addresses the bottom side of an 8.5" x 11" page, and 792 addresses the top side.

Default: calculated as paper_height - 126, see wkPaperSize

wkDeviceUpperY (PSWorkstation)

Default: calculated as paper_height - 126, see wkPaperSize

wkFileName (DocumentWorkstation)

This resource specifies the name of the output file.

Default: <dynamic>

wkFileName (ImageWorkstation)

This resource specifies the name of the output file.

Default: <dynamic>

wkFillTableLength (Workstation)

This read-only resource contains the number of currently available unique fill patterns.

Default: <dynamic>

wkForegroundColor (Workstation)

This resource can be a one-dimensional array containing three elements of type NhlTFloat that specify (in order) the red, green, and blue components (an RGB triplet) of the Workstation foreground color, or a string containing a color name from the file $NCARG_ROOT/lib/ncarg/database/rgb.txt. The foreground color is equivalent to HLU color index 1 (the defined constant NhlFOREGROUND when using the C language interface). It is the first element of the wkColorMap array (index 0 of the array when using the C interface). Unlike wkBackgroundColor, you may set wkForegroundColor at any time during the life of the Workstation object.

If you set wkForegroundColor and wkColorMap at the same time, the set value of the first element of wkColorMap will be replaced with the value of wkForegroundColor. If neither wkForegroundColor nor wkColorMap is set when the Workstation object is created, the foreground is determined dynamically.

Default: <dynamic>
If background color is determined to be closer to black than white, the foreground color is set to white (1.0, 1.0, 1.0); otherwise the foreground color is set to black (0.0, 0.0, 0.0).

wkFormat (DocumentWorkstation)

This resource is used to specify which output format should be produced; use "ps" for postscript output, "pdf" for PDF output, "eps" for encapsulated-postscript, or "svg" for scalable vector graphics format.

Default: "ps"

wkFormat (ImageWorkstation)

This resource is used to specify which output format should be produced. Currently, only PNG is supported, specified as "png".

Default: "png"

wkFullBackground (PDFWorkstation)

If this resource is True, then the entire output page will have the background color applied to it. If it is False, then only the normalized device coordinate viewport will be effected by the background color. The background is the first thing drawn on the page. Therefore, if this resource is modified after something has been drawn, it will not change the background for the current page. It will effectively change for the next page of the output.

Default: False

wkFullBackground (PSWorkstation)

Default: False

wkGksWorkId (Workstation)

This read-only resource contains the low-level GKS workstation identifier. It can be used to mix calls to the low-level NCAR Graphics library and the GKS library with the HLU library. The HLU library expects the GKS workstation to be in a deactivated state. Therefore, any set of low-level calls occurring between HLU library calls should be bracketed by a GKS activate workstation call and a GKS deactivate workstation call.

Default: <dynamic>
This value is determined by the low-level GKS library.

wkHeight (ImageWorkstation)

This resource specifies the height, in pixels, of the resultant image.

Default: 1024

wkMarkerTableLength (Workstation)

This read-only resource contains the number of currently available unique markers.

Default: <dynamic>

wkMetaName (NcgmWorkstation)

Specifies the name and path of the output metafile. By default a file called gmeta will be created in the current working directory. The NcgmWorkstation object will attempt to resolve pathnames that start with the "~" character.

Default: "gmeta"

wkOrientation (DocumentWorkstation)

This resource is used to indicate if the PS or PDF output should be produced in "portrait" mode (pictures displayed along the width of the paper or viewing window) or "landscape" mode (pictures displayed along the length).

Default: "portrait"

wkOrientation (PDFWorkstation)

This resource is used to indicate if the PDF output should be produced in "portrait" mode (pictures displayed along the width of the paper or viewing window) or "landscape" mode (pictures displayed along the length).

Default: "portrait"

wkOrientation (PSWorkstation)

This resource is used to indicate if the PostScript output should be produced in "portrait" mode (pictures displayed along the width of the paper or viewing window) or "landscape" mode (pictures displayed along the length).

Default: "portrait"

wkPDFFileName (PDFWorkstation)

This resource is used to specify the name of the PDF file to output. If a wkPDFFileName of "stdout" is given, the PDFWorkstation understands the output should be sent to the stream associated with the stdout FILE pointer in the UNIX environment. The PDFWorkstation object will attempt to resolve pathnames that start with the "~" character.

Default: <dynamic>
This resource defaults to the name of the PDFWorkstation object with the wkPDFFormat as a suffix. For example, "workname.pdf".

wkPDFFormat (PDFWorkstation)

This resource is used to specify which Portable Document Format (PDF) should be produced. Currently, the PDFWorkstation can produce only "pdf" formatted documents.

Default: "pdf"

wkPDFResolution (PDFWorkstation)

This resource indicates the resolution of the internal coordinate space of the PDF file. This resource is used to increase or decrease the resolution of the output. The effective resolution you get on a particular PDF printer or screen display depends on the resolution of the internal PDF coordinate system as well as the resolution of the output device. The units of this resource are compatible with DPI (Dots Per Inch). If wkPDFResolution is set to a number that is greater than or equal to the resolution of the printer, then you can be sure that you are making full use of the resolution of the printer. It is important to realize that printers that have a lower resolution can print PDF files that have a higher internal coordinate space resolution without problems, since the internal coordinate space resolution just indicates the resolution of the points within the file's coordinate space. If the PDF output is generated with a lower internal coordinate space resolution then the printer, the full resolution of the printer will not be utilized.

Changing the value for wkPDFResolution will usually not change the size of the PDF output file; if it does, the files will differ by only a few bytes.

Default: 1800

wkPSFileName (PSWorkstation)

This resource is used to specify the name of the PostScript file to output. If a wkPSFileName of "stdout" is given, the PSWorkstation understands the output should be sent to the stream associated with the stdout FILE pointer in the UNIX environment. The PSWorkstation object will attempt to resolve pathnames that start with the "~" character.

Default: <dynamic>
This resource defaults to the name of the PSWorkstation object with the wkPSFormat as a suffix. For example, "workname.ps".

wkPSFormat (PSWorkstation)

This resource is used to specify which PostScript format should be produced. Currently, the PSWorkstation can produce generic "ps", EPS (Encapsulated PostScript) "eps", and EPSI (Encapsulated PostScript Interchange format) "epsi".

EPS is a specialized format used primarily for importing PostScript into other applications. EPS files contain information in them, that allow an importing application to know the extent of the marks on the PostScript page. They are also restricted to a single page of output in them.

EPSI are EPS files that have a "preview bitmap" that represents the PostScript image contained in the file. This bitmap can be used by an importing application to display quickly a picture of the imported file. This is used by applications that do not have a built-in PostScript interpreter. As of Version 4.0, the "preview bitmap" output by the PSWorkstation does not represent the picture contained in the EPSI file, but rather is simply a bitmap containing the message: APPLICATION CANNOT DISPLAY NCAR GRAPHIC HERE. VIEW THE POSTSCRIPT OUTPUT TO VERIFY SUCCESSFUL IMPORT.

Default: "ps"

wkPSResolution (PSWorkstation)

This resource indicates the resolution of the internal coordinate space of the PostScript file. This resource is used to increase or decrease the resolution of the output. The effective resolution you get on a particular PostScript printer or screen display depends on the resolution of the internal PostScript coordinate system as well as the resolution of the output device. The units of this resource are compatible with DPI (Dots Per Inch). If wkPSResolution is set to a number that is greater than or equal to the resolution of the printer, then you can be sure that you are making full use of the resolution of the printer. It is important to realize that printers that have a lower resolution can print PostScript files that have a higher internal coordinate space resolution without problems, since the internal coordinate space resolution just indicates the resolution of the points within the file's coordinate space. If the PostScript is generated with a lower internal coordinate space resolution then the printer, the full resolution of the printer will not be utilized.

One advantage of lowering the wkPSResolution would be to make the actual size of the PostScript file smaller, although the difference is rather modest.

Default: 1800

wkPaperHeightF (DocumentWorkstation)

This resource can be used to specify the height of the paper, in inches. Must be used in conjunction with wkPaperWidthF. If these two resources are used along with wkPaperSize, the value for wkPaperSize will prevail.

Default: 11 inches

wkPaperHeightF (PDFWorkstation)

Available in version 5.2.0 and later.

Default: 11 inches

wkPaperHeightF (PSWorkstation)

Available in version 5.2.0 and later.

Default: 11 inches

wkPaperSize (DocumentWorkstation)

This resource can be used to specify a standard paper size by name. Currently recognized names are:

                    ANSI/U.S. paper sizes

        name        points     inches    millimeters
        "A"        612  792   8.5  11.0   216  279
        "letter"   612  792   8.5  11.0   216  279
        "legal"    612 1008   8.5  14.0   216  356
        "B"        792 1224  11.0  17.0   279  432
        "ledger"   792 1224  11.0  17.0   279  432
        "superA3"  936 1368  13.0  19.0   330  483
        "superB"   936 1368  13.0  19.0   330  483
        "C"       1224 1584  17.0  22.0   432  559
        "D"       1584 2520  22.0  34.0   559  864
        "E"       2448 3168  34.0  44.0   864 1118
       
                    ISO/Metric paper sizes 
        "A5"       418  598   5.8   8.3   148  210
        "A4"       598  842   8.3  11.7   210  297
        "A3"       842 1188  11.7  16.5   297  420
        "A3+"      936 1368  13.0  19.0   329  483
        "A2"      1188 1685  16.5  23.4   420  594
        "A1"      1685 2383  23.4  33.1   594  841
        "A0"      2383 3370  33.1  46.8   841 1189

Default: "letter"

wkPaperSize (PDFWorkstation)

This resource can be used to specify a standard paper size by name. Currently recognized names are:

                    ANSI/U.S. paper sizes

        name        points     inches    millimeters
        "A"        612  792   8.5  11.0   216  279
        "letter"   612  792   8.5  11.0   216  279
        "legal"    612 1008   8.5  14.0   216  356
        "B"        792 1224  11.0  17.0   279  432
        "ledger"   792 1224  11.0  17.0   279  432
        "superA3"  936 1368  13.0  19.0   330  483
        "superB"   936 1368  13.0  19.0   330  483
        "C"       1224 1584  17.0  22.0   432  559
        "D"       1584 2520  22.0  34.0   559  864
        "E"       2448 3168  34.0  44.0   864 1118
       
                    ISO/Metric paper sizes 
        "A5"       418  598   5.8   8.3   148  210
        "A4"       598  842   8.3  11.7   210  297
        "A3"       842 1188  11.7  16.5   297  420
        "A3+"      936 1368  13.0  19.0   329  483
        "A2"      1188 1685  16.5  23.4   420  594
        "A1"      1685 2383  23.4  33.1   594  841
        "A0"      2383 3370  33.1  46.8   841 1189

Available in version 5.2.0 and later.

Default: "letter"

wkPaperSize (PSWorkstation)

This resource can be used to specify a standard paper size by name. Currently recognized names are:

                    ANSI/U.S. paper sizes

        name        points     inches    millimeters
        "A"        612  792   8.5  11.0   216  279
        "letter"   612  792   8.5  11.0   216  279
        "legal"    612 1008   8.5  14.0   216  356
        "B"        792 1224  11.0  17.0   279  432
        "ledger"   792 1224  11.0  17.0   279  432
        "superA3"  936 1368  13.0  19.0   330  483
        "superB"   936 1368  13.0  19.0   330  483
        "C"       1224 1584  17.0  22.0   432  559
        "D"       1584 2520  22.0  34.0   559  864
        "E"       2448 3168  34.0  44.0   864 1118
       
                    ISO/Metric paper sizes 
        "A5"       418  598   5.8   8.3   148  210
        "A4"       598  842   8.3  11.7   210  297
        "A3"       842 1188  11.7  16.5   297  420
        "A3+"      936 1368  13.0  19.0   329  483
        "A2"      1188 1685  16.5  23.4   420  594
        "A1"      1685 2383  23.4  33.1   594  841
        "A0"      2383 3370  33.1  46.8   841 1189

Available in version 5.2.0 and later.

Default: "letter"

wkPaperWidthF (DocumentWorkstation)

This resource can be used to specify the width of the paper, in inches. Must be used in conjunction with wkPaperHeightF. If these two resources are used along with wkPaperSize, the value for wkPaperSize will prevail.

Default: 8.5 inches

wkPaperWidthF (PDFWorkstation)

Available in version 5.2.0 and later.

Default: 8.5 inches

wkPaperWidthF (PSWorkstation)

Available in version 5.2.0 and later.

Default: 8.5 inches

wkTopLevelViews (Workstation)

This read-only array resource contains the ids of only those View children of the Workstation that may be drawn directly. This list excludes all View objects that are currently plot members.

Default: <dynamic>

wkViews (Workstation)

This read-only array resource contains the ids of all View object children of the Workstation. This list includes View objects that are plot members.

Default: <dynamic>

wkVisualType (PDFWorkstation)

This resource is used to indicate if the PDF file should produce "color", or "monochrome" output. Color output can be displayed on a grayscale printer, and the colors will be mapped to shades of gray. If "monochrome" output is selected, all colors, except the background color, will be mapped to the foreground color. If you are plotting a color image on a grayscale printer and find the results unsatisfactory since colors are getting mapped to light shades of gray that are difficult to see, it may be better to produce the picture in "monochrome".

Default: "color"

wkVisualType (PSWorkstation)

This resource is used to indicate if the PostScript file should produce "color", or "monochrome" output. Color output can be displayed on a grayscale printer, and the colors will be mapped to shades of gray. If "monochrome" output is selected, all colors, except the background color, will be mapped to the foreground color. If you are plotting a color image on a grayscale printer and find the results unsatisfactory since colors are getting mapped to light shades of gray that are difficult to see, it may be better to produce the picture in "monochrome".

Default: "color"

wkWidth (ImageWorkstation)

This resource specifies the width, in pixels, of the resultant image.

Default: 1024