Canvas

Canvas objects are the ‘visualization’ component of VCS. Canvases allow the user to take data and plot it on a visible window. This gives users an easy way to preview how changes to data representation in VCS will change the visualization of that data.

class vcs.Canvas.Canvas(mode=1, pause_time=0, call_from_gui=0, size=None, backend='vtk', geometry=None, bg=None, display_target=None)[source]

Usually created using vcs.init(), this object provides easy access to the functionality of the entire VCS module:

See vcs.Canvas.Canvas.plot() for more information on the type of data that can be plotted on a Canvas object.

addfont(path, name='')[source]

Add a font to VCS.

Parameters
  • path (str) – Path to the font file you wish to add (must be .ttf)

  • name (str) – Name to use to represent the font.

boxfill(*args, **parms)[source]
Generate a boxfill plot given the data, boxfill graphics method, and

template. If no boxfill object is given, then the ‘default’ boxfill graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('boxfill') # Show all boxfills
*******************Boxfill Names List**********************
...
*******************End Boxfill Names List**********************
>>> box=a.getboxfill('quick') # Create instance of 'quick'
>>> arr=[range(10) for _ in range(10)] # data to plot
>>> a.boxfill(arr, box) # Plot array w/ box; default template
<vcs.displayplot.Dp ...>
>>> t = a.gettemplate('quick') # get quick template
>>> a.clear() # Clear VCS canvas
>>> a.boxfill(arr, box, t) # Plot w/ box and 'quick' template
<vcs.displayplot.Dp ...>
>>> a.boxfill(box, arr, t) # Plot w/ box and 'quick' template
<vcs.displayplot.Dp ...>
>>> a.boxfill(t, arr, box) # Plot w/ box and 'quick' template
<vcs.displayplot.Dp ...>
>>> a.boxfill(t, box, arr) # Plot w/ box and 'quick' template
<vcs.displayplot.Dp ...>
>>> a.boxfill(arr, 'polar', 'polar') # 'polar' template/boxfill
<vcs.displayplot.Dp ...>
>>> a.boxfill('polar', arr, 'polar') # 'polar' template/boxfill
<vcs.displayplot.Dp ...>
>>> a.boxfill('polar', 'polar', arr) # 'polar' template/boxfill
<vcs.displayplot.Dp ...>

Note

As shown above, the data, ‘template’, and ‘box’ parameters can be provided in any order. The ‘template’ and ‘box’ parameters can either be VCS template and boxfill objects, or string names of template and boxfill objects.

The first string provided is assumed to be a template name. The second is assumed to be a boxfill name.

Parameters
  • xaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -1 dim axis. (keyword parameter)

  • yaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -2 dim axis, only if slab has more than 1D. (keyword parameter)

  • zaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -3 dim axis, only if slab has more than 2D. (keyword parameter)

  • taxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -4 dim axis, only if slab has more than 3D. (keyword parameter)

  • waxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -5 dim axis, only if slab has more than 4D. (keyword parameter)

  • xrev (bool) – reverse x axis. (keyword parameter)

  • yrev (bool) – reverse y axis, only if slab has more than 1D. (keyword parameter)

  • xarray (array) – Values to use instead of x axis. (keyword parameter)

  • yarray (array) – Values to use instead of y axis, only if var has more than 1D. (keyword parameter)

  • zarray (array) – Values to use instead of z axis, only if var has more than 2D. (keyword parameter)

  • tarray (array) – Values to use instead of t axis, only if var has more than 3D. (keyword parameter)

  • warray (array) – Values to use instead of w axis, only if var has more than 4D. (keyword parameter)

  • continents (int) – continents type number. (keyword parameter)

  • name (str) – replaces variable name on plot. (keyword parameter)

  • time (A cdtime object) – replaces time name on plot. (keyword parameter)

  • units (str) – replaces units value on plot. (keyword parameter)

  • ymd (str) – replaces year/month/day on plot. (keyword parameter)

  • hms (str) – replaces hh/mm/ss on plot. (keyword parameter)

  • file_comment (str) – replaces file_comment on plot. (keyword parameter)

  • xbounds (array) – Values to use instead of x axis bounds values. (keyword parameter)

  • ybounds (array) – Values to use instead of y axis bounds values (if exist). (keyword parameter)

  • xname (str) – replace xaxis name on plot. (keyword parameter)

  • yname (str) – replace yaxis name on plot (if exists). (keyword parameter)

  • zname (str) – replace zaxis name on plot (if exists). (keyword parameter)

  • tname (str) – replace taxis name on plot (if exists). (keyword parameter)

  • wname (str) – replace waxis name on plot (if exists). (keyword parameter)

  • xunits (str) – replace xaxis units on plot. (keyword parameter)

  • yunits (str) – replace yaxis units on plot (if exists). (keyword parameter)

  • zunits (str) – replace zaxis units on plot (if exists). (keyword parameter)

  • tunits (str) – replace taxis units on plot (if exists). (keyword parameter)

  • wunits (str) – replace waxis units on plot (if exists). (keyword parameter)

  • xweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • yweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • comment1 (str) – replaces comment1 on plot. (keyword parameter)

  • comment2 (str) – replaces comment2 on plot. (keyword parameter)

  • comment3 (str) – replaces comment3 on plot. (keyword parameter)

  • comment4 (str) – replaces comment4 on plot. (keyword parameter)

  • long_name (str) – replaces long_name on plot. (keyword parameter)

  • grid (cdms2.grid.TransientRectGrid) – replaces array grid (if exists). (keyword parameter)

  • bg (bool/int) – plots in background mode. (keyword parameter)

  • ratio () – sets the y/x ratio ,if passed as a string with ‘t’ at the end, will aslo moves the ticks. (keyword parameter)

  • xaxisconvert (str) – (Ex: ‘linear’) converting xaxis linear/log/log10/ln/exp/area_wt

  • yaxisconvert (str) – (Ex: ‘linear’) converting yaxis linear/log/log10/ln/exp/area_wt

  • slab (array) – (Ex: [[0, 1]]) Data at least 2D, last 2 dimensions will be plotted

Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

canvasid(*args)[source]

Get the ID of this canvas. This ID number is found at the top of the VCS Canvas, as part of its title.

Example
>>> a=vcs.init()
>>> cid = a.canvasid() # store the canvas id
Returns

The ID of the canvas on which canvasid() is called.

Return type

int

canvasinfo(*args, **kargs)[source]

Obtain the current attributes of the VCS Canvas window.

Example
>>> a=vcs.init()
>>> ci=a.canvasinfo()
>>> keys=sorted(a.canvasinfo().keys())
>>> for key in keys:
...     print(key, str(ci[key]))
depth ...
height ...
mapstate ...
width ...
x ...
y ...
Returns

Dictionary with keys: “mapstate” (whether the canvas is opened), “height”, “width”, “depth”, “x”, “y”

Return type

dict

cgm(file, mode='w')[source]

Deprecated since version 2.6.1: Exporting images to CGM format is no longer supported. To generate an image from the canvas, see vcs.Canvas.Canvas.png() or vcs.Canvas.Canvas.svg()

Export an image in CGM format.

Parameters
  • file – Filename to save

  • mode – Ignored.

change_display_graphic_method(display, type, name)[source]

Changes the type and graphic method of a plot.

Example
>>> a=vcs.init()
>>> cdgm=a.change_display_graphic_method # alias long name
>>> array=[range(10) for _ in range(10)]
>>> disp=a.plot(array)
>>> a.show('boxfill') # list boxfill names
*******************Boxfill Names List**********************
...
*******************End Boxfill Names List**********************
>>> cdgm(disp, 'boxfill', 'polar') # change graphics method
Parameters
  • display (str or vcs.displayplot.Dp) – Display to change.

  • type (str) – New graphics method type.

  • name (str) – Name of new graphics method.

check_name_source(name, source, typ)[source]

Make sure it is a unique name for this type or generates a name for user.

Example
>>> cns=vcs.check_name_source # alias for long function name
>>> vcs.show('boxfill')
*******************Boxfill Names List**********************
...
*******************End Boxfill Names List**********************
>>> cns('NEW', 'quick', 'boxfill') # name 'NEW' should be available
('NEW', 'quick')
>>> cns(None, 'default', 'boxfill') # generate unique boxfill name
('__boxfill_...', 'default')
Parameters
  • name (str or None) – Desired string name for an object of type typ, inheriting from source object source. If name is None, a unique name will be generated.

  • source (str or VCS Object) – Source from which the new object is meant to inherit. Can be a VCS object or a string name of a VCS object.

  • typ (str) – String name of a VCS object type. (e.g. ‘boxfill’, ‘isofill’, ‘marker’, etc.)

Returns

A tuple containing two strings: a unique name and a source name. If name was provided and an object of type typ with that name already exists, an error is raised.

Return type

tuple

clean_auto_generated_objects(type=None)[source]

Cleans up all automatically generated VCS objects.

This function will delete all references to objects that VCS created automatically in response to user actions but are no longer in use. This shouldn’t be necessary most of the time, but if you’re running into performance/memory issues, calling it periodically may help.

Example
>>> a=vcs.init()
>>> clean=a.clean_auto_generated_objects # alias long name
>>> clean() # clean possible old objects from vcs
>>> txt=a.listelements('textorientation') # initial objects
>>> array=[range(10) for _ in range(10)]
>>> a.plot(array)
<vcs.displayplot.Dp object at 0x...>
>>> new_txt=a.listelements('textorientation') # has new names
>>> txt == new_txt # should not be the same
False
>>> clean()
>>> new_txt=a.listelements('textorientation') # back to initial
>>> txt == new_txt # should have the same contents
True
Parameters

type (None, str, list/tuple (of str)) – Type of objects to remove. By default, will remove all object types.

clear(*args, **kargs)[source]

Clears all the VCS displays on a page (i.e., the VCS Canvas object).

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
>>> a.clear() # clear VCS displays from the page
close(*args, **kargs)[source]

Close the VCS Canvas. It will not deallocate the VCS Canvas object. To deallocate the VCS Canvas, use the destroy method.

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
>>> a.close() #close the vcs canvas
copyfontto(font1, font2)[source]

Copy ‘font1’ into ‘font2’.

Parameters
  • font1 (str or int) – Name/number of font to copy

  • font2 (str or int) – Name/number of destination

Attention

This function does not currently work. It will be added in the future.

create1d(name=None, source='default')[source]

Creates a new vcs.unified1d.G1d object called name, and inheriting from source.

Example
>>> vcs.show('1d')
*******************1d Names List**********************
...
*******************End 1d Names List**********************
>>> vcs.create1d() # inherits default, name generated
<vcs.unified1D.G1d ...>
>>> vcs.create1d("one_D") # inherits default, name "one_D"
<vcs.unified1D.G1d ...>
>>> vcs.create1d(source="one_D") # inherits from "one_D"
<vcs.unified1D.G1d ...>
Parameters
  • name (str) – A string name for the 1d to be created. If None, a unique name will be created.

  • source (str or vcs.unified1D.G1d) – A 1d object or string name of a 1d object from which the new 1d will inherit.

Returns

A new 1d object, inheriting from source.

Return type

vcs.unified1D.G1d

create3d_dual_scalar(name=None, source='default')[source]

Create a new dv3d graphics method given the the name and the existing dv3d graphics method to copy attributes from. If no existing dv3d graphics method is given, the default dv3d graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('3d_dual_scalar') # list 3d_dual_scalars
[...]
>>> ex=vcs.create3d_dual_scalar('3d_dual_scalar_ex1')
>>> vcs.listelements('3d_dual_scalar') # includes new object
[...'3d_dual_scalar_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.dv3d.Gf3DDualScalar) – The object to inherit from. Can be a 3d_dual_scalar, or a string name of a 3d_dual_scalar.

Returns

A 3d_dual_scalar graphics method object

Return type

vcs.dv3d.Gf3DDualScalar

create3d_scalar(name=None, source='default')[source]

Create a new dv3d graphics method given the the name and the existing dv3d graphics method to copy attributes from. If no existing dv3d graphics method is given, the default dv3d graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('3d_scalar') # list 3d_scalars
[...]
>>> ex=vcs.create3d_scalar('3d_scalar_ex1')
>>> vcs.listelements('3d_scalar') # includes new object
[...'3d_scalar_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.dv3d.Gf3Dscalar) – The object to inherit from. Can be a 3d_scalar, or a string name of a 3d_scalar.

Returns

A 3d_scalar graphics method object

Return type

vcs.dv3d.Gf3Dscalar

create3d_vector(name=None, source='default')[source]

Create a new dv3d graphics method given the the name and the existing dv3d graphics method to copy attributes from. If no existing dv3d graphics method is given, the default dv3d graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('3d_vector') # list 3d_vectors
[...]
>>> ex=vcs.create3d_vector('3d_vector_ex1')
>>> vcs.listelements('3d_vector') # includes new object
[...'3d_vector_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.dv3d.Gf3Dvector) – The object to inherit from. Can be a 3d_vector, or a string name of a 3d_vector.

Returns

A 3d_vector graphics method object

Return type

vcs.dv3d.Gf3Dvector

createboxfill(name=None, source='default')[source]

Create a new boxfill graphics method given the the name and the existing boxfill graphics method to copy attributes from. If no existing boxfill graphics method is given, the default boxfill graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('boxfill') # list boxfills
[...]
>>> ex=vcs.createboxfill('boxfill_ex1')
>>> vcs.listelements('boxfill') # includes new object
[...'boxfill_ex1'...]
>>> ex2=vcs.createboxfill('boxfill_ex2','polar')
>>> vcs.listelements('boxfill') # includes new object
[...'boxfill_ex2'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.boxfill.Gfb) – The object to inherit from. can be a boxfill, or a string name of a boxfill.

Returns

A boxfill graphics method object

Return type

vcs.boxfill.Gfb

createcolormap(Cp_name=None, Cp_name_src='default')[source]

Create a new colormap secondary method given the the name and the existing colormap secondary method to copy attributes from. If no existing colormap secondary method is given, the default colormap secondary method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. secondary method names must be unique.

Example
>>> vcs.listelements('colormap') # list colormaps
[...]
>>> ex=vcs.createcolormap('colormap_ex1')
>>> vcs.listelements('colormap') # includes new object
[...'colormap_ex1'...]
>>> ex2=vcs.createcolormap('colormap_ex2','rainbow')
>>> vcs.listelements('colormap') # includes new object
[...'colormap_ex2'...]
Parameters
  • Cp_name (str) – The name of the created object

  • Cp_name_src (str or vcs.colormap.Cp) – The object to inherit from. Can be a colormap or a string name of a colormap.

Returns

A VCS colormap object

Return type

vcs.colormap.Cp

createfillarea(name=None, source='default', style=None, index=None, color=None, priority=1, viewport=None, worldcoordinate=None, x=None, y=None)[source]

Create a new fillarea secondary method given the the name and the existing fillarea secondary method to copy attributes from. If no existing fillarea secondary method is given, the default fillarea secondary method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. secondary method names must be unique.

Example
>>> vcs.listelements('fillarea') # list fillareas
[...]
>>> ex=vcs.createfillarea('fillarea_ex1')
>>> vcs.listelements('fillarea') # includes new object
[...'fillarea_ex1'...]
Parameters
  • name (str) – Name of created object

  • source (str) – a fillarea, or string name of a fillarea

  • style (str) – One of “hatch”, “solid”, or “pattern”.

  • index (int) – Specifies which pattern to fill with. Accepts ints from 1-20.

  • color (str or int) – A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the fillarea will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

Returns

A fillarea object

Return type

vcs.fillarea.Tf

createisofill(name=None, source='default')[source]

Create a new isofill graphics method given the the name and the existing isofill graphics method to copy attributes from. If no existing isofill graphics method is given, the default isofill graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('isofill') # list isofills
[...]
>>> ex=vcs.createisofill('isofill_ex1')
>>> vcs.listelements('isofill') # includes new object
[...'isofill_ex1'...]
>>> ex2=vcs.createisofill('isofill_ex2','polar')
>>> vcs.listelements('isofill') # includes new object
[...'isofill_ex2'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.isofill.Gfi) – The object to inherit from. Can be an isofill object, or string name of an isofill object.

Returns

An isofill graphics method

Return type

vcs.isofill.Gfi

createisoline(name=None, source='default')[source]

Create a new isoline graphics method given the the name and the existing isoline graphics method to copy attributes from. If no existing isoline graphics method is given, the default isoline graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('isoline') # list isolines
[...]
>>> ex=vcs.createisoline('isoline_ex1')
>>> vcs.listelements('isoline') # includes new object
[...'isoline_ex1'...]
>>> ex2=vcs.createisoline('isoline_ex2','polar')
>>> vcs.listelements('isoline') # includes new object
[...'isoline_ex2'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.isoline.Gi) – The object to inherit from. Can be an isoline object, or string name of an isoline object.

Returns

An isoline graphics method object

Return type

vcs.isoline.Gi

createline(name=None, source='default', ltype=None, width=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, projection=None)[source]

Create a new line secondary method given the the name and the existing line secondary method to copy attributes from. If no existing line secondary method is given, the default line secondary method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. secondary method names must be unique.

Example
>>> vcs.listelements('line') # list lines
[...]
>>> ex=vcs.createline('line_ex1')
>>> vcs.listelements('line') # includes new object
[...'line_ex1'...]
>>> ex2=vcs.createline('line_ex2','red')
>>> vcs.listelements('line') # includes new object
[...'line_ex2'...]
Parameters
  • name (str) – Name of created object

  • source (str) – a line, or string name of a line

  • ltype (str) – One of “dash”, “dash-dot”, “solid”, “dot”, or “long-dash”.

  • width (int) – Thickness of the line to be created

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the line will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

  • projection (str or projection object) – Specify a geographic projection used to convert x/y from spherical coordinates to 2D coordinates.

Returns

A VCS line secondary method object

Return type

vcs.line.Tl

createmarker(name=None, source='default', mtype=None, size=None, color=None, priority=1, viewport=None, worldcoordinate=None, x=None, y=None, projection=None)[source]

Create a new marker secondary method given the the name and the existing marker secondary method to copy attributes from. If no existing marker secondary method is given, the default marker secondary method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. secondary method names must be unique.

Example
>>> vcs.listelements('marker') # list markers
[...]
>>> ex=vcs.createmarker('marker_ex1')
>>> vcs.listelements('marker') # includes new object
[...'marker_ex1'...]
>>> ex2=vcs.createmarker('marker_ex2','red')
>>> vcs.listelements('marker') # includes new object
[...'marker_ex2'...]
Parameters
  • name (str) – Name of created object

  • source (str) – A marker, or string name of a marker

  • mtype (str) – Specifies the type of marker, i.e. “dot”, “circle”

  • size (int) –

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the marker will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

Returns

A secondary marker method

Return type

vcs.marker.Tm

createmeshfill(name=None, source='default')[source]

Create a new meshfill graphics method given the the name and the existing meshfill graphics method to copy attributes from. If no existing meshfill graphics method is given, the default meshfill graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('meshfill') # list meshfills
[...]
>>> ex=vcs.createmeshfill('meshfill_ex1')
>>> vcs.listelements('meshfill') # includes new object
[...'meshfill_ex1'...]
>>> ex2=vcs.createmeshfill('meshfill_ex2','a_polar_meshfill')
>>> vcs.listelements('meshfill') # includes new object
[...'meshfill_ex2'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.meshfill.Gfm) – The object to inherit from. Can be a meshfill, or a string name of a meshfill.

Returns

A meshfill graphics method object

Return type

vcs.meshfill.Gfm

createprojection(name=None, source='default')[source]

Create a new projection graphics method given the the name and the existing projection graphics method to copy attributes from. If no existing projection graphics method is given, the default projection graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('projection') # list projections
[...]
>>> ex=vcs.createprojection('projection_ex1')
>>> vcs.listelements('projection') # includes new object
[...'projection_ex1'...]
>>> ex2=vcs.createprojection('projection_ex2','orthographic')
>>> vcs.listelements('projection') # includes new object
[...'projection_ex2'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.projection.Proj) – The object to inherit from. Can be a projection, or a string name of a projection.

Returns

A projection graphics method object

Return type

vcs.projection.Proj

createscatter(name=None, source='default')[source]

Create a new scatter graphics method given the the name and the existing scatter graphics method to copy attributes from. If no existing scatter graphics method is given, the default scatter graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('scatter') # list scatters
[...]
>>> ex=vcs.createscatter('scatter_ex1')
>>> vcs.listelements('scatter') # includes new object
[...'scatter_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.unified1D.G1d) – The object to inherit from. Can be a scatter or, a string name of a scatter.

Returns

A scatter graphics method

Return type

vcs.unified1D.G1d

createstreamline(name=None, source='default')[source]

Create a new streamline graphics method given the the name and the existing streamline graphics method to copy attributes from. If no existing streamline graphics method is given, the default streamline graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('streamline') # list streamlines
[...]
>>> ex=vcs.createstreamline('streamline_ex1')
>>> vcs.listelements('streamline') # includes new object
[...'streamline_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (a streamline or a string name of a streamline) – The object to inherit from

Returns

A streamline graphics method object

Return type

vcs.streamline.Gs

createtaylordiagram(name=None, source='default')[source]

Create a new taylordiagram graphics method given the the name and the existing taylordiagram graphics method to copy attributes from. If no existing taylordiagram graphics method is given, the default taylordiagram graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('taylordiagram') # list taylordiagrams
[...]
>>> ex=vcs.createtaylordiagram('taylordiagram_ex1')
>>> vcs.listelements('taylordiagram') # includes new object
[...'taylordiagram_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.taylor.Gtd) – The object to inherit from. Can be a a taylordiagram, or a string name of a taylordiagram.

Returns

A taylordiagram graphics method object

Return type

vcs.taylor.Gtd

createtemplate(name=None, source='default')[source]

Create a new template graphics method given the the name and the existing template graphics method to copy attributes from. If no existing template graphics method is given, the default template graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('template') # list templates
[...]
>>> ex=vcs.createtemplate('template_ex1')
>>> vcs.listelements('template') # includes new object
[...'template_ex1'...]
>>> ex2=vcs.createtemplate('template_ex2','polar')
>>> vcs.listelements('template') # includes new object
[...'template_ex2'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.template.P) – The object to inherit from. Can be a template, or a string name of a template

Returns

A template

Return type

vcs.template.P

createtext(Tt_name=None, Tt_source='default', To_name=None, To_source='default', font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, height=None, angle=None, path=None, halign=None, valign=None, projection=None)

Create a new textcombined secondary method given the the name and the existing textcombined secondary method to copy attributes from. If no existing textcombined secondary method is given, the default textcombined secondary method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. secondary method names must be unique.

Example
>>> vcs.listelements('textcombined') # list textcombineds
[...]
>>> try: # try to create a new textcombined, in case none exist
...     tc = vcs.createtextcombined('EX_tt', 'qa', 'EX_tto', '7left')
... except:
...     pass
>>> vcs.listelements('textcombined') # includes new object
[...'EX_tt:::EX_tto'...]
Parameters
  • Tt_name (str) – Name of created object

  • Tt_source (str or vcs.texttable.Tt) – Texttable object to inherit from. Can be a texttable, or a string name of a texttable.

  • To_name (str) – Name of the textcombined’s text orientation (to be created)

  • To_source (str or vcs.textorientation.To) – Name of the textorientation to inherit. Can be a textorientation, or a string name of a textorientation.

  • font (int or str) – Which font to use (index or name).

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the object will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

  • height (int) – Size of the font

  • angle (int) – Angle of the text, in degrees

  • halign (str) – Horizontal alignment of the text. One of [“left”, “center”, “right”].

  • valign (str) – Vertical alignment of the text. One of [“top”, “center”, “botom”].

  • projection (str or projection object) – Specify a geographic projection used to convert x/y from spherical coordinates to 2D coordinates.

Returns

A VCS text object

Return type

vcs.textcombined.Tc

Note

The spacing, path, and expansion parameters are no longer used

createtextcombined(Tt_name=None, Tt_source='default', To_name=None, To_source='default', font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, height=None, angle=None, path=None, halign=None, valign=None, projection=None)[source]

Create a new textcombined secondary method given the the name and the existing textcombined secondary method to copy attributes from. If no existing textcombined secondary method is given, the default textcombined secondary method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. secondary method names must be unique.

Example
>>> vcs.listelements('textcombined') # list textcombineds
[...]
>>> try: # try to create a new textcombined, in case none exist
...     tc = vcs.createtextcombined('EX_tt', 'qa', 'EX_tto', '7left')
... except:
...     pass
>>> vcs.listelements('textcombined') # includes new object
[...'EX_tt:::EX_tto'...]
Parameters
  • Tt_name (str) – Name of created object

  • Tt_source (str or vcs.texttable.Tt) – Texttable object to inherit from. Can be a texttable, or a string name of a texttable.

  • To_name (str) – Name of the textcombined’s text orientation (to be created)

  • To_source (str or vcs.textorientation.To) – Name of the textorientation to inherit. Can be a textorientation, or a string name of a textorientation.

  • font (int or str) – Which font to use (index or name).

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the object will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

  • height (int) – Size of the font

  • angle (int) – Angle of the text, in degrees

  • halign (str) – Horizontal alignment of the text. One of [“left”, “center”, “right”].

  • valign (str) – Vertical alignment of the text. One of [“top”, “center”, “botom”].

  • projection (str or projection object) – Specify a geographic projection used to convert x/y from spherical coordinates to 2D coordinates.

Returns

A VCS text object

Return type

vcs.textcombined.Tc

Note

The spacing, path, and expansion parameters are no longer used

createtextorientation(name=None, source='default')[source]

Create a new textorientation secondary method given the the name and the existing textorientation secondary method to copy attributes from. If no existing textorientation secondary method is given, the default textorientation secondary method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. secondary method names must be unique.

Example
>>> vcs.listelements('textorientation') # list textorientations
[...]
>>> ex=vcs.createtextorientation('textorientation_ex1')
>>> vcs.listelements('textorientation') # includes new object
[...'textorientation_ex1'...]
>>> ex2=vcs.createtextorientation('textorientation_ex2','bigger')
>>> vcs.listelements('textorientation') # includes new object
[...'textorientation_ex2'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.textorientation.To) – The object to inherit from. Can be a textorientation, or a string name of a textorientation.

Returns

A textorientation secondary method

Return type

vcs.textorientation.To

createtexttable(name=None, source='default', font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None)[source]

Create a new texttable secondary method given the the name and the existing texttable secondary method to copy attributes from. If no existing texttable secondary method is given, the default texttable secondary method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. secondary method names must be unique.

Example
>>> vcs.listelements('texttable') # list texttables
[...]
>>> ex=vcs.createtexttable('texttable_ex1')
>>> vcs.listelements('texttable') # includes new object
[...'texttable_ex1'...]
>>> ex2=vcs.createtexttable('texttable_ex2','bigger')
>>> vcs.listelements('texttable') # includes new object
[...'texttable_ex2'...]
Parameters
  • name (str) – Name of created object

  • source (str) – a texttable, or string name of a texttable

  • font (int or str) – Which font to use (index or name).

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the texttable will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

Returns

A texttable graphics method object

Return type

vcs.texttable.Tt

Note

The expansion parameter is no longer used

createvector(name=None, source='default')[source]

Create a new vector graphics method given the the name and the existing vector graphics method to copy attributes from. If no existing vector graphics method is given, the default vector graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('vector') # list vectors
[...]
>>> ex=vcs.createvector('vector_ex1')
>>> vcs.listelements('vector') # includes new object
[...'vector_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.vector.Gv) – The object to inherit from. Can be a vector, or a string name of a vector.

Returns

A vector graphics method object

Return type

vcs.vector.Gv

createxvsy(name=None, source='default')[source]

Create a new xvsy graphics method given the the name and the existing xvsy graphics method to copy attributes from. If no existing xvsy graphics method is given, the default xvsy graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('xvsy') # list xvsys
[...]
>>> ex=vcs.createxvsy('xvsy_ex1')
>>> vcs.listelements('xvsy') # includes new object
[...'xvsy_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.unified1D.G1d) – The object to inherit from. Can be a xvsy, or a string name of a xvsy.

Returns

A XvsY graphics method object

Return type

vcs.unified1D.G1d

createxyvsy(name=None, source='default')[source]

Create a new xyvsy graphics method given the the name and the existing xyvsy graphics method to copy attributes from. If no existing xyvsy graphics method is given, the default xyvsy graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('xyvsy') # list xyvsys
[...]
>>> ex=vcs.createxyvsy('xyvsy_ex1')
>>> vcs.listelements('xyvsy') # includes new object
[...'xyvsy_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.unified1D.G1d) – The object to inherit from. Can be a xyvsy, or a string name of a xyvsy.

Returns

A XYvsY graphics method object

Return type

vcs.unified1D.G1d

createyxvsx(name=None, source='default')[source]

Create a new yxvsx graphics method given the the name and the existing yxvsx graphics method to copy attributes from. If no existing yxvsx graphics method is given, the default yxvsx graphics method will be used as the graphics method from which attributes will be copied.

Note

If the name provided already exists, then an error will be returned. graphics method names must be unique.

Example
>>> vcs.listelements('yxvsx') # list yxvsxs
[...]
>>> ex=vcs.createyxvsx('yxvsx_ex1')
>>> vcs.listelements('yxvsx') # includes new object
[...'yxvsx_ex1'...]
Parameters
  • name (str) – The name of the created object

  • source (str or vcs.unified1D.G1d) – The object to inherit from. Can be a yxvsy, or a string name of a yxvsy.

Returns

A YXvsX graphics method object

Return type

vcs.unified1D.G1d

destroy()[source]

Destroy the VCS Canvas. It will deallocate the VCS Canvas object.

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
>>> a.destroy()
drawfillarea(name=None, style=1, index=1, color=241, priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, bg=0)[source]

Generate and draw a fillarea object on the VCS Canvas.

Example
>>> a=vcs.init()
>>> a.show('fillarea') # Show all the existing fillarea objects
*******************Fillarea Names List**********************
...
*******************End Fillarea Names List**********************
>>> fa=a.drawfillarea(name='red', style=1, color=242,
...              priority=1, viewport=[0, 1.0, 0, 1.0],
...              worldcoordinate=[0,100, 0,50],
...              x=[0,20,40,60,80,100],
...              y=[0,10,20,30,40,50], bg=0 ) # Create instance of fillarea object 'red'
>>> a.fillarea(fa) # Plot using specified fillarea object
<vcs.displayplot.Dp ...>
Parameters
  • name (str) – Name of the object to be created.

  • style (str) – One of “hatch”, “solid”, or “pattern”.

  • index (int) – Specifies which pattern to fill the fillarea with. Accepts ints from 1-20.

  • color (str or int or tuple) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the object will be drawn.

  • viewport (list of floats) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be floats between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be floats between worldcoordinate[2] and worldcoordinate[3].

  • bg (bool) – Boolean value. True => object drawn in background (not shown on canvas). False => object shown on canvas.

Returns

A fillarea object

Return type

vcs.fillarea.Tf

drawline(name=None, ltype='solid', width=1, color=241, priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, projection='default', bg=0)[source]

Generate and draw a line object on the VCS Canvas.

Example
>>> a=vcs.init()
>>> a.show('line') # Show all the existing line objects
*******************Line Names List**********************
...
*******************End Line Names List**********************
>>> ln=a.drawline(name='red', ltype='dash', width=2,
...              color=242, priority=1, viewport=[0, 1.0, 0, 1.0],
...              worldcoordinate=[0,100, 0,50],
...              x=[0,20,40,60,80,100],
...              y=[0,10,20,30,40,50] )
>>> a.line(ln) # Plot using specified line object
<vcs.displayplot.Dp ...>
Parameters
  • name (str) – Name of the object to be created.

  • ltype (str) – One of “dash”, “dash-dot”, “solid”, “dot”, or “long-dash”.

  • width (int) – Thickness of the line to be drawn

  • color (str or int or tuple) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the object will be drawn.

  • viewport (list of floats) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be floats between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be floats between worldcoordinate[2] and worldcoordinate[3].

  • projection (str or vcs.projection.Proj) – Specifies a geographic projection used to convert x/y from spherical coordinates into 2D coordinates. Can be a VCS projection or a string name of a projection

Returns

A VCS line object

Return type

vcs.line.Tl

drawlogooff()[source]

Hide UV-CDAT logo on the canvas

Example
>>> a=vcs.init()
>>> a.drawlogooff()
>>> a.getdrawlogo()
False
drawlogoon()[source]

Show UV-CDAT logo on the canvas

Example
>>> a=vcs.init()
>>> a.drawlogoon()
>>> a.getdrawlogo()
True
drawmarker(name=None, mtype='solid', size=1, color=241, priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, bg=0)[source]

Generate and draw a marker object on the VCS Canvas.

Example
>>> a=vcs.init()
>>> a.show('marker')  # Show all the existing marker objects
*******************Marker Names List**********************
...
*******************End Marker Names List**********************
>>> mrk=a.drawmarker(name='red', mtype='dot', size=2,
...              color=242, priority=1, viewport=[0, 1.0, 0, 1.0],
...              worldcoordinate=[0,100, 0,50],
...              x=[0,20,40,60,80,100],
...              y=[0,10,20,30,40,50] ) # Create instance of marker object 'red'
>>> a.marker(mrk) # Plot using specified marker object
<vcs.displayplot.Dp ...>
Parameters
  • name (str) – Name of the object to be created.

  • mtype (str) – Marker type, i.e. ‘dot’, ‘plus’, ‘star, etc.

  • size (int) – Size of the marker to draw

  • color (str or int or tuple) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the object will be drawn.

  • viewport (list of floats) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be floats between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be floats between worldcoordinate[2] and worldcoordinate[3].

  • bg (bool) – Boolean value. True => object drawn in background (not shown on canvas). False => object shown on canvas.

Returns

A drawmarker object

Return type

vcs.marker.Tm

drawtext(Tt_name=None, To_name=None, string=None, font=1, spacing=2, expansion=100, color=241, height=14, angle=0, path='right', halign='left', valign='half', priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, bg=0)

Draw a textcombined object on the VCS Canvas.

Example
>>> a=vcs.init()
>>> drawtc=a.drawtextcombined # alias long function name
>>> a.show('texttable') # Show all the existing texttable objects
*******************Texttable Names List**********************
...
*******************End Texttable Names List**********************
>>> if "draw_tt" in vcs.listelements("texttable"): vcs.reset()
>>> if "draw_tto" in vcs.listelements("textorientation"): vcs.reset()
>>> vcs.createtextcombined('draw_tt','qa', 'draw_tto', '7left')
<vcs.textcombined.Tc object at 0x...>
>>> msg=["Hello", "drawtextcombined!"]
>>> tc=drawtc(Tt_name='draw_tt',To_name='draw_tto',string=msg)
Parameters
  • Tt_name (str) – String name of a texttable object

  • To_name (str) – String name of a textorientation object

  • string (str) – String to put onto the new textcombined

  • color (str or int or tuple) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • viewport (list of floats) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be floats between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be floats between worldcoordinate[2] and worldcoordinate[3].

  • bg (bool) – Boolean value. True => object drawn in background (not shown on canvas). False => object shown on canvas.

Returns

A texttable object

Return type

vcs.texttable.Tt

drawtextcombined(Tt_name=None, To_name=None, string=None, font=1, spacing=2, expansion=100, color=241, height=14, angle=0, path='right', halign='left', valign='half', priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, bg=0)[source]

Draw a textcombined object on the VCS Canvas.

Example
>>> a=vcs.init()
>>> drawtc=a.drawtextcombined # alias long function name
>>> a.show('texttable') # Show all the existing texttable objects
*******************Texttable Names List**********************
...
*******************End Texttable Names List**********************
>>> if "draw_tt" in vcs.listelements("texttable"): vcs.reset()
>>> if "draw_tto" in vcs.listelements("textorientation"): vcs.reset()
>>> vcs.createtextcombined('draw_tt','qa', 'draw_tto', '7left')
<vcs.textcombined.Tc object at 0x...>
>>> msg=["Hello", "drawtextcombined!"]
>>> tc=drawtc(Tt_name='draw_tt',To_name='draw_tto',string=msg)
Parameters
  • Tt_name (str) – String name of a texttable object

  • To_name (str) – String name of a textorientation object

  • string (str) – String to put onto the new textcombined

  • color (str or int or tuple) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • viewport (list of floats) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be floats between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be floats between worldcoordinate[2] and worldcoordinate[3].

  • bg (bool) – Boolean value. True => object drawn in background (not shown on canvas). False => object shown on canvas.

Returns

A texttable object

Return type

vcs.texttable.Tt

dual_scalar3d(*args, **parms)[source]

Generate a 3d_dual_scalar plot given the data, 3d_dual_scalar graphics method, and template. If no 3d_dual_scalar object is given, then the ‘default’ 3d_dual_scalar graphics method is used. Similarly, if no template is given, the ‘default’ template is used.

Note

3d_dual_scalars need 2 data objects (slabs) to plot.

Example
>>> a=vcs.init()
>>> a.show('3d_dual_scalar') # Show all 3d_dual_scalars
*******************3d_dual_scalar Names List**********************
...
*******************End 3d_dual_scalar Names List**********************
>>> ds3=a.get3d_dual_scalar() # default 3d_dual_scalar
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data file
>>> s = f('clt') # use data file to create a cdms2 slab
>>> s2 = f('v') # need two slabs, so get another
>>> # Plot slabs
>>> a.dual_scalar3d(ds3, s, s2)  
initCamera: Camera => (...)
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> t = a.gettemplate('polar')
>>> # Plot w/ 'polar' template
>>> a.dual_scalar3d(s,s2,ds3,t)  
initCamera: Camera => (...)
<vcs.displayplot.Dp ...>
dummy_user_action(*args, **kargs)[source]

Given args and kargs, prints the arguments and keyword arguments associated with those parameters.

Use this function to test what args and kargs are, if you’re unsure.

Example
>>> a=vcs.init()
>>> dua=a.dummy_user_action # alias long name
>>> dua("falafel", 37, the_answer=42)
Arguments: ('falafel', 37)
Keywords: {'the_answer': 42}
Parameters
  • args (any) – Any number of arguments, without a keyword specifier.

  • kargs (any) – Any number of keyword arguments, associated with any number of data (i.e. kwd1=”a string”, kwd2=42).

eps(file, mode='r', orientation=None, width=None, height=None, units='inches', textAsPaths=True)[source]

In some cases, the user may want to save the plot out as an Encapsulated PostScript image. This routine allows the user to save the VCS canvas output as an Encapsulated PostScript file. This file can be converted to other image formats with the aid of xv and other such imaging tools found freely on the web.

Example
>>> a=vcs.init()
>>> array = [range(10) for _ in range(10)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.postscript('example') # Overwrite a postscript file
>>> a.postscript('example', 'a') # Append postscript to an existing file
>>> a.postscript('example', 'r') # Overwrite an existing file
>>> a.postscript('example', mode='a') # Append postscript to an existing file
>>> a.postscript('example', width=11.5, height= 8.5) # US Legal (default)
>>> a.postscript('example', width=21, height=29.7, units='cm') # A4
Parameters
  • file (str) – Desired string name of the output file

  • mode (str) – The mode in which to open the file. One of ‘r’ or ‘a’.

  • width (float) – Float specifying the desired width of the output, in the specified unit of measurement.

  • height (float) – Float specifying the desired height of the output, measured in the chosen units

  • units (str) – One of [‘inches’, ‘in’, ‘cm’, ‘mm’, ‘pixel’, ‘pixels’, ‘dot’, ‘dots’]. Defaults to ‘inches’.

ffmpeg(movie, files, bitrate=1024, rate=None, options=None)[source]

MPEG output from a list of valid files. Can output to more than just mpeg format.

Note

ffmpeg ALWAYS overwrites the output file

Audio configuration

via the options arg you can add audio file to your movie (see ffmpeg help)

Example
>>> a=vcs.init()
>>> import cdms2
>>> f = cdms2.open(vcs.sample_data+'/clt.nc')
>>> v = f('v') # use the data file to create a cdms2 slab
>>> u = f('u') # use the data file to create a cdms2 slab
>>> png_files = [] # for saving file names to make the mpeg
>>> for i in range(10): # create a number of pngs to use for an mpeg
...     a.clear()
...     if (i%2):
...         a.plot(u,v)
...     else:
...         a.plot(v,u)
...     a.png('my_png__%i' % i)
...     png_files.append('my_png__%i.png' % i)
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
<vcs.displayplot.Dp object at 0x...>
>>> a.ffmpeg('m1.mpeg',png_files) # using list of files
<vcs.Canvas.JupyterFFMPEG object at 0x...>
>>> a.ffmpeg('m2.mpeg',png_files,bitrate=512) # 512kbit rate
<vcs.Canvas.JupyterFFMPEG object at 0x...>
>>> a.ffmpeg('m3.mpeg',png_files,rate=50) # 50 frames/second
<vcs.Canvas.JupyterFFMPEG object at 0x...>
Parameters
  • movie (str) – Output video file name

  • files (str, list, or tuple) – String name of a file, or a list or tuple of multiple file names

  • rate (str) – Desired output framerate

  • options (str) – Additional FFMPEG arguments

Returns

A object that Jupyter notebook can display

Return type

JupyterFFMPEG

fillarea(*args, **parms)[source]

Generate a fillarea plot

Plot a fillarea segment on the Vcs Canvas. If no fillarea class object is given, then an error will be returned.

Example
>>> a=vcs.init()
>>> a.show('fillarea') # Show all fillarea objects
*******************Fillarea Names List**********************
...
*******************End Fillarea Names List**********************
>>> fa=a.createfillarea() # instance of default fillarea
>>> fa.style=1 # Set fillarea style
>>> fa.index=4 # Set fillarea index
>>> fa.color = 242 # Set fillarea color
>>> fa.x=[0.25,0.75] # Set x value points
>>> fa.y=[0.2,0.5] # Set y value points
>>> a.fillarea(fa) # Plot using specified fillarea object
<vcs.displayplot.Dp ...>
Returns

A fillarea object

Return type

vcs.displayplot.Dp

flush(*args)[source]

The flush command executes all buffered X events in the queue.

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
>>> a.flush()
geometry(*args)[source]

The geometry command is used to set the size and position of the VCS canvas.

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
>>> a.geometry(450,337)
get1d(name)[source]

Given name, returns a vcs.unified1d.G1d from vcs with that name. Unlike other VCS ‘get’ functions, name cannot be None when calling get1d().

Example
>>> vcs.show('1d')
*******************1d Names List**********************
...
*******************End 1d Names List**********************
>>> vcs.get1d('blue_yxvsx')
<vcs.unified1D.G1d ...>
Parameters

name (str) – String name of a 1d in vcs. If there is no 1d with that name, an error will be raised.

Returns

A 1d from vcs with the given name.

Return type

vcs.unified1d.G1d

get3d_dual_scalar(Gfdv3d_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a dv3d object from an existing VCS dv3d graphics method. If no dv3d name is given, then default dv3d will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.create3d_dual_scalar() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('3d_dual_scalar') # list all 3d_dual_scalars
[...]
>>> ex=vcs.get3d_dual_scalar()  # 'default' 3d_dual_scalar
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> slab2 = f('v') # need 2 slabs, so get another
Parameters

Gfdv3d_name_src (str) – String name of an existing 3d_dual_scalar VCS object

Returns

A pre-existing 3d_dual_scalar VCS object

Return type

vcs.dv3d.Gf3DDualScalar

get3d_scalar(Gfdv3d_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a dv3d object from an existing VCS dv3d graphics method. If no dv3d name is given, then default dv3d will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.create3d_scalar() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('3d_scalar') # list all 3d_scalars
[...]
>>> ex=vcs.get3d_scalar()  # 'default' 3d_scalar
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
Parameters

Gfdv3d_name_src (str) – String name of an existing 3d_scalar VCS object.

Returns

A pre-existing 3d_scalar VCS object

Return type

vcs.dv3d.Gf3Dscalar

get3d_vector(Gfdv3d_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a dv3d object from an existing VCS dv3d graphics method. If no dv3d name is given, then default dv3d will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.create3d_vector() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('3d_vector') # list all 3d_vectors
[...]
>>> ex=vcs.get3d_vector()  # 'default' 3d_vector
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> slab2 = f('v') # need 2 slabs, so get another
Parameters

Gfdv3d_name_src (str) – String name of an existing 3d_vector VCS object

Returns

A pre-existing 3d_vector VCS object

Return type

vcs.dv3d.Gf3Dvector

get_selected_display()[source]

Attention

This function does not currently work. It will be implemented in the future.

getantialiasing()[source]

Returns the current antialiasing rate for the canvas.

Example
>>> a=vcs.init()
>>> a.setantialiasing(0) # turn off antialiasing
>>> a.getantialiasing() # will return current antialiasing rate
0
Returns

antialiasing rate for the canvas

Return type

int

getboxfill(Gfb_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a boxfill object from an existing VCS boxfill graphics method. If no boxfill name is given, then default boxfill will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createboxfill() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('boxfill') # list all boxfills
[...]
>>> ex=vcs.getboxfill()  # 'default' boxfill
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> a.boxfill(ex, slab1) # plot boxfill
<vcs.displayplot.Dp ...>
>>> ex2=vcs.getboxfill('polar')  # boxfill #2
>>> a.boxfill(ex2, slab1) # plot boxfill
<vcs.displayplot.Dp ...>
Parameters

Gfb_name_src (str) – String name of an existing boxfill VCS object

Returns

A pre-existing boxfill graphics method

Return type

vcs.boxfill.Gfb

getcolorcell(*args)[source]

Gets the colorcell of the provided object’s colormap at the specified cell index. If no object is provided, or if the provided object has no colormap, the default colormap is used.

Example
>>> a=vcs.init()
>>> b=vcs.createboxfill()
>>> b.colormap='rainbow'
>>> a.getcolorcell(2,b)
[26, 1, 34, 100]
Parameters
  • cell (int) – An integer value indicating the index of the desired colorcell.

  • obj (Any VCS object capable of containing a colormap) – Optional parameter with the object to get a colormap from.

Returns

The RGBA values of the colormap at the specified cell index.

Return type

list

getcolormap(Cp_name_src='default')[source]

VCS contains a list of secondary methods. This function will create a colormap object from an existing VCS colormap secondary method. If no colormap name is given, then default colormap will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createcolormap() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('colormap') # list all colormaps
[...]
>>> ex=vcs.getcolormap()  # 'default' colormap
>>> ex2=vcs.getcolormap('rainbow')  # colormap #2
Parameters

Cp_name_src (str) – String name of an existing colormap VCS object

Returns

A pre-existing VCS colormap object

Return type

vcs.colormap.Cp

getcolormapname()[source]

Returns the name of the colormap this canvas is set to use by default.

Example
>>> a=vcs.init()
>>> a.show('colormap')
*******************Colormap Names List**********************
...
*******************End Colormap Names List**********************
>>> a.setcolormap('rainbow') # set canvas's default colormap
>>> a.getcolormapname()
'rainbow'

To set that colormap, use setcolormap().

getcontinentsline()[source]

Returns the continents line associated with the canvas.

Example
>>> a=vcs.init()
>>> cl=a.getcontinentsline() # should be the default
>>> cl.name
'default'
Returns

The line object associated with the canvas’s continents_line property

Return type

vcs.line.Tl

Returns value of draw logo. By default, draw logo is set to True.

Example
>>> a=vcs.init()
>>> a.getdrawlogo()
True
>>> a.drawlogooff()
>>> a.getdrawlogo()
False
Returns

Boolean value of system variable which indicates whether logo will be drawn

Return type

bool

getfillarea(name='default', style=None, index=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None)[source]

VCS contains a list of secondary methods. This function will create a fillarea object from an existing VCS fillarea secondary method. If no fillarea name is given, then default fillarea will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createfillarea() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('fillarea') # list all fillareas
[...]
>>> ex=vcs.getfillarea()  # 'default' fillarea
>>> a.fillarea(ex) # plot fillarea
<vcs.displayplot.Dp ...>
Parameters
  • name (str) – String name of an existing fillarea VCS object

  • style (str) – One of “hatch”, “solid”, or “pattern”.

  • index (int) –

    Specifies which pattern to fill with. Accepts ints from 1-20.

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the texttable will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

Returns

A fillarea secondary object

Return type

vcs.fillarea.Tf

getfont(font)[source]

Get the font name/number associated with a font number/name

Example
>>> font_names=[]
>>> for i in range(1,17):
...     font_names.append(str(vcs.getfont(i))) # font_names is now filled with all font names
>>> font_names
['default', ...]
>>> font_numbers = []
>>> for name in font_names:
...     font_numbers.append(vcs.getfont(name)) # font_numbers is now filled with all font numbers
>>> font_numbers
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
Parameters

font (int or str) – The font name/number

Returns

If font parameter was a string, will return the integer associated with that string. If font parameter was an integer, will return the string associated with that integer.

Return type

int or str

getfontname(number)[source]

Retrieve a font name for a given font index.

Example
>>> vcs.getfontname(1)
'default'
>>> vcs.getfontname(4)
'Helvetica'
Parameters

number (int) – Index of the font to get the name of.

getfontnumber(name)[source]

Retrieve a font index for a given font name.

Example
>>> vcs.getfontnumber('default')
1
>>> vcs.getfontnumber('Helvetica')
4
Parameters

name (str) – Name of the font to get the index of.

getisofill(Gfi_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a isofill object from an existing VCS isofill graphics method. If no isofill name is given, then default isofill will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createisofill() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('isofill') # list all isofills
[...]
>>> ex=vcs.getisofill()  # 'default' isofill
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> a.isofill(ex, slab1) # plot isofill
<vcs.displayplot.Dp ...>
>>> ex2=vcs.getisofill('polar')  # isofill #2
>>> a.isofill(ex2, slab1) # plot isofill
<vcs.displayplot.Dp ...>
Parameters

Gfi_name_src (str) – String name of an existing isofill VCS object

Returns

The specified isofill VCS object

Return type

vcs.isofill.Gfi

getisoline(Gi_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a isoline object from an existing VCS isoline graphics method. If no isoline name is given, then default isoline will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createisoline() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('isoline') # list all isolines
[...]
>>> ex=vcs.getisoline()  # 'default' isoline
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> a.isoline(ex, slab1) # plot isoline
<vcs.displayplot.Dp ...>
>>> ex2=vcs.getisoline('polar')  # isoline #2
>>> a.isoline(ex2, slab1) # plot isoline
<vcs.displayplot.Dp ...>
Parameters

Gi_name_src (str) – String name of an existing isoline VCS object

Returns

The requested isoline VCS object

Return type

vcs.isoline.Gi

getline(name='default', ltype=None, width=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None)[source]

VCS contains a list of secondary methods. This function will create a line object from an existing VCS line secondary method. If no line name is given, then default line will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createline() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('line') # list all lines
[...]
>>> ex=vcs.getline()  # 'default' line
>>> a.line(ex) # plot line
<vcs.displayplot.Dp ...>
>>> ex2=vcs.getline('red')  # line #2
>>> a.line(ex2) # plot line
<vcs.displayplot.Dp ...>
Parameters
  • name (str) – Name of created object

  • ltype (str) – One of “dash”, “dash-dot”, “solid”, “dot”, or “long-dash”.

  • width (int) – Thickness of the line to be created

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the marker will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

Returns

A VCS line object

Return type

vcs.line.Tl

getmarker(name='default', mtype=None, size=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None)[source]

VCS contains a list of secondary methods. This function will create a marker object from an existing VCS marker secondary method. If no marker name is given, then default marker will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createmarker() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('marker') # list all markers
[...]
>>> ex=vcs.getmarker()  # 'default' marker
>>> a.marker(ex) # plot marker
<vcs.displayplot.Dp ...>
>>> ex2=vcs.getmarker('red')  # marker #2
>>> a.marker(ex2) # plot marker
<vcs.displayplot.Dp ...>
Parameters
  • name (str) – Name of created object

  • source (str) – A marker, or string name of a marker

  • mtype (str) – Specifies the type of marker, i.e. “dot”, “circle”

  • size (int) – Size of the marker

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the marker will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

Returns

A marker graphics method object

Return type

vcs.marker.Tm

getmeshfill(Gfm_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a meshfill object from an existing VCS meshfill graphics method. If no meshfill name is given, then default meshfill will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createmeshfill() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('meshfill') # list all meshfills
[...]
>>> ex=vcs.getmeshfill()  # 'default' meshfill
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> a.meshfill(ex, slab1) # plot meshfill
<vcs.displayplot.Dp ...>
>>> ex2=vcs.getmeshfill('a_polar_meshfill')  # meshfill #2
>>> a.meshfill(ex2, slab1) # plot meshfill
<vcs.displayplot.Dp ...>
Parameters

Gfm_name_src (str) – String name of an existing meshfill VCS object

Returns

A meshfill VCS object

Return type

vcs.meshfill.Gfm

getplot(Dp_name_src='default', template=None)[source]

This function will create a display plot object from an existing display plot object from an existing VCS plot. If no display plot name is given, then None is returned.

Parameters
  • Dp_name_src (str) – String name of an existing display plot object

  • template – The displayplot template to inherit from

Returns

A VCS displayplot object

Return type

vcs.displayplot.Dp

Attention

This function does not currently work. It will be implemented in the future.

getprojection(Proj_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a projection object from an existing VCS projection graphics method. If no projection name is given, then default projection will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createprojection() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('projection') # list all projections
[...]
>>> ex=vcs.getprojection()  # 'default' projection
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> ex2=vcs.getprojection('orthographic')  # projection #2
Parameters

Proj_name_src (str) – String name of an existing VCS projection object

Returns

A VCS projection object

Return type

vcs.projection.Proj

getscatter(GSp_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a scatter object from an existing VCS scatter graphics method. If no scatter name is given, then ‘default_scatter_’ scatter will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createscatter() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('scatter') # list all scatters
[...]
>>> ex=vcs.getscatter('default_scatter_')  # ''default_scatter_'' scatter
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> slab2 = f('v') # need 2 slabs, so get another
>>> a.scatter(ex, slab1, slab2) # plot scatter
<vcs.displayplot.Dp ...>
Parameters

GSp_name_src (str) – String name of an existing scatter VCS object.

Returns

A scatter graphics method object

Return type

vcs.unified1D.G1d

getstreamline(Gv_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a streamline object from an existing VCS streamline graphics method. If no streamline name is given, then default streamline will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createstreamline() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('streamline') # list all streamlines
[...]
>>> ex=vcs.getstreamline()  # 'default' streamline
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> slab2 = f('v') # need 2 slabs, so get another
>>> a.streamline(ex, slab1, slab2) # plot streamline
<vcs.displayplot.Dp ...>
Parameters

Gs_name_src (str) – String name of an existing streamline VCS object

Returns

A streamline graphics method object

Return type

vcs.streamline.Gs

gettaylordiagram(Gtd_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a taylordiagram object from an existing VCS taylordiagram graphics method. If no taylordiagram name is given, then default taylordiagram will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createtaylordiagram() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('taylordiagram') # list all taylordiagrams
[...]
>>> ex=vcs.gettaylordiagram()  # 'default' taylordiagram
>>> slab1 = [[0, 1, 2, 3, 4], [0.1, 0.2, 0.3, 0.4, 0.5]] # data
>>> a.taylordiagram(ex, slab1) # plot taylordiagram
<vcs.displayplot.Dp ...>
Parameters

Gtd_name_src (str) – String name of an existing taylordiagram VCS object

Returns

A taylordiagram VCS object

Return type

vcs.taylor.Gtd

gettemplate(Pt_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a template object from an existing VCS template graphics method. If no template name is given, then default template will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createtemplate() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('template') # list all templates
[...]
>>> ex=vcs.gettemplate()  # 'default' template
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> ex2=vcs.gettemplate('polar')  # template #2
Parameters

Pt_name_src (str) – String name of an existing template VCS object

Returns

A VCS template object

Return type

vcs.template.P

gettext(Tt_name_src='default', To_name_src=None, string=None, font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, height=None, angle=None, path=None, halign=None, valign=None)

VCS contains a list of secondary methods. This function will create a textcombined object from an existing VCS textcombined secondary method. If no textcombined name is given, then EX_tt:::EX_tto textcombined will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createtextcombined() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('textcombined') # list all textcombineds
[...]
>>> try: # try to create a new textcombined, in case none exist
...     tc = vcs.createtextcombined('EX_tt', 'qa', 'EX_tto', '7left')
... except:
...     pass
>>> ex=vcs.gettextcombined('EX_tt', 'EX_tto')  # 'EX_tt:::EX_tto' textcombined
>>> a.textcombined(ex) # plot textcombined
<vcs.displayplot.Dp ...>
Parameters
  • Tt_name_src (str) – Name of parent texttable object

  • To_name_src (str) – Name of parent textorientation object

  • string (list) – Text to render

  • font (int or str) – Which font to use (index or name)

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the object will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

  • height (int) – Size of the font

  • angle (list) – Angle of the rendered text, in degrees. Must be a list of integers.

  • halign (str) – Horizontal alignment of the text. One of [“left”, “center”, “right”]

  • valign (str) – Vertical alignment of the text. One of [“top”, “center”, “bottom”]

Returns

A textcombined object

Return type

vcs.textcombined.Tc

Note

The spacing, path, and expansion parameters are no longer used

gettextbox(textobject)[source]

Returns the coordinate of the exact and rotated box surrounding a text object once printed

Example
>>> a=vcs.init()
>>> t=a.createtext()
>>> t.x=[.5]
>>> t.y=[.5]
>>> t.string=['Hello World']
>>> a.gettextbox(t)
[[...]]
Parameters

textobject (vcs.textcombined.Tc) – A VCS text object

Returns

2 list of floats containing the coordinates of the text object’s box. One for xs one for ys

coordinates are appropriate within the same viewport and worldcoordinate as the input textobject :rtype: list

gettextcombined(Tt_name_src='default', To_name_src=None, string=None, font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, height=None, angle=None, path=None, halign=None, valign=None)[source]

VCS contains a list of secondary methods. This function will create a textcombined object from an existing VCS textcombined secondary method. If no textcombined name is given, then EX_tt:::EX_tto textcombined will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createtextcombined() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('textcombined') # list all textcombineds
[...]
>>> try: # try to create a new textcombined, in case none exist
...     tc = vcs.createtextcombined('EX_tt', 'qa', 'EX_tto', '7left')
... except:
...     pass
>>> ex=vcs.gettextcombined('EX_tt', 'EX_tto')  # 'EX_tt:::EX_tto' textcombined
>>> a.textcombined(ex) # plot textcombined
<vcs.displayplot.Dp ...>
Parameters
  • Tt_name_src (str) – Name of parent texttable object

  • To_name_src (str) – Name of parent textorientation object

  • string (list) – Text to render

  • font (int or str) – Which font to use (index or name)

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the object will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

  • height (int) – Size of the font

  • angle (list) – Angle of the rendered text, in degrees. Must be a list of integers.

  • halign (str) – Horizontal alignment of the text. One of [“left”, “center”, “right”]

  • valign (str) – Vertical alignment of the text. One of [“top”, “center”, “bottom”]

Returns

A textcombined object

Return type

vcs.textcombined.Tc

Note

The spacing, path, and expansion parameters are no longer used

gettextextent(textobject, angle=None)[source]

Returns the coordinate of the box surrounding a text object once printed

Example
>>> a=vcs.init()
>>> t=a.createtext()
>>> t.x=[.5]
>>> t.y=[.5]
>>> t.string=['Hello World']
>>> a.gettextextent(t)
[[...]]
Parameters
  • textobject (vcs.textcombined.Tc) – A VCS text object

  • angle – If not None overwrites the textobject’s angle (in degrees)

Returns

list of floats containing the coordinates of the text object’s bounding box.

coordinates are appropriate within the same viewport and worldcoordinate as the input textobject :rtype: list

gettextorientation(To_name_src='default')[source]

VCS contains a list of secondary methods. This function will create a textorientation object from an existing VCS textorientation secondary method. If no textorientation name is given, then default textorientation will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createtextorientation() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('textorientation') # list all textorientations
[...]
>>> ex=vcs.gettextorientation()  # 'default' textorientation
>>> ex2=vcs.gettextorientation('bigger')  # textorientation #2
Parameters

To_name_src (str) – String name of an existing textorientation VCS object

Returns

A textorientation VCS object

Return type

vcs.textorientation.To

gettexttable(name='default', font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None)[source]

VCS contains a list of secondary methods. This function will create a texttable object from an existing VCS texttable secondary method. If no texttable name is given, then default texttable will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createtexttable() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('texttable') # list all texttables
[...]
>>> ex=vcs.gettexttable()  # 'default' texttable
>>> ex2=vcs.gettexttable('bigger')  # texttable #2
Parameters
  • name (str) – String name of an existing VCS texttable object

  • font (int or str) – Which font to use (index or name).

  • color (str or int) –

    A color name from the X11 Color Names list, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50))

  • priority (int) – The layer on which the texttable will be drawn.

  • viewport (list) – 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas.

  • worldcoordinate (list) – List of 4 floats (xmin, xmax, ymin, ymax)

  • x (list) – List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1].

  • y (list) – List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3].

Returns

A texttable graphics method object

Return type

vcs.texttable.Tt

Note

The expansion parameter is no longer used

getvector(Gv_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a vector object from an existing VCS vector graphics method. If no vector name is given, then default vector will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createvector() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('vector') # list all vectors
[...]
>>> ex=vcs.getvector()  # 'default' vector
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> slab2 = f('v') # need 2 slabs, so get another
>>> a.vector(ex, slab1, slab2) # plot vector
<vcs.displayplot.Dp ...>
Parameters

Gv_name_src (str) – String name of an existing vector VCS object

Returns

A vector graphics method object

Return type

vcs.vector.Gv

getxvsy(GXY_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a xvsy object from an existing VCS xvsy graphics method. If no xvsy name is given, then default_xvsy_ xvsy will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createxvsy() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('xvsy') # list all xvsys
[...]
>>> ex=vcs.getxvsy()  # 'default_xvsy_' xvsy
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> slab2 = f('v') # need 2 slabs, so get another
>>> a.xvsy(ex, slab1, slab2) # plot xvsy
<vcs.displayplot.Dp ...>
Parameters

GXY_name_src (str) – String name of a 1d graphics method

Returns

A XvsY graphics method object

Return type

vcs.unified1D.G1d

getxyvsy(GXy_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a xyvsy object from an existing VCS xyvsy graphics method. If no xyvsy name is given, then ‘default_xyvsy_’ xyvsy will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createxyvsy() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('xyvsy') # list all xyvsys
[...]
>>> ex=vcs.getxyvsy('default_xyvsy_')  # ''default_xyvsy_'' xyvsy
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> a.xyvsy(ex, slab1) # plot xyvsy
<vcs.displayplot.Dp ...>
Parameters

GXy_name_src (str) – String name of an existing Xyvsy graphics method

Returns

An XYvsY graphics method object

Return type

vcs.unified1D.G1d

getyxvsx(GYx_name_src='default')[source]

VCS contains a list of graphics methods. This function will create a yxvsx object from an existing VCS yxvsx graphics method. If no yxvsx name is given, then default_yxvsx_ yxvsx will be used.

Note

VCS does not allow the modification of ‘default’ attribute sets. However, a ‘default’ attribute set that has been copied under a different name can be modified. (See the vcs.manageElements.createyxvsx() function.)

Example
>>> a=vcs.init()
>>> vcs.listelements('yxvsx') # list all yxvsxs
[...]
>>> ex=vcs.getyxvsx()  # 'default_yxvsx_' yxvsx
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2
>>> slab1 = f('u') # take a slab from the data
>>> a.yxvsx(ex, slab1) # plot yxvsx
<vcs.displayplot.Dp ...>
Parameters

GYx_name_src (str) – String name of an existing Yxvsx graphics method

Returns

A Yxvsx graphics method object

Return type

vcs.unified1D.G1d

gif(filename='noname.gif', merge='r', orientation=None, geometry='1600x1200')[source]

In some cases, the user may want to save the plot out as a gif image. This routine allows the user to save the VCS canvas output as a SUN gif file. This file can be converted to other gif formats with the aid of xv and other such imaging tools found freely on the web.

By default, the page orientation is in Landscape mode (l). To translate the page orientation to portrait mode (p), set the orientation = ‘p’.

The GIF command is used to create or append to a gif file. There are two modes for saving a gif file: ‘Append’ mode (a) appends gif output to an existing gif file; ‘Replace’ (r) mode overwrites an existing gif file with new gif output. The default mode is to overwrite an existing gif file (i.e. mode (r)).

Attention

This function does not currently work. It will be implemented in the future.

initLogoDrawing()[source]

Initializes logo drawing for the canvas.

Example
>>> a=vcs.init()
>>> a.initLogoDrawing() # will draw logo when plot is called
>>> array=[range(10) for _ in range(10)]
>>> a.plot(array) # should have logo in lower right corner
<vcs.displayplot.Dp object at 0x...>
interact(*args, **kargs)[source]

Puts the canvas into interactive mode. This allows the user to click on the canvas to add markers, add textboxes, configure settings, rotate 3d plots, and more.

Press ‘Q’ with the Canvas selected to quit.

Example
a=vcs.init()
b=a.getboxfill()
array=[range(10) for _ in range(10)]
a.plot(b,array)
a.interact() # interactively configure Canvas
islandscape()[source]

Indicates if VCS’s orientation is landscape.

Returns a 1 if orientation is landscape. Otherwise, it will return a 0, indicating false (not in landscape mode).

Example
>>> a=vcs.init()
>>> array = [range(10) for _ in range(10)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> if a.islandscape():
...     a.portrait() # Set VCS's orientation to portrait mode
Returns

Integer indicating VCS is in landscape mode (1), or not (0)

Return type

int

isofill(*args, **parms)[source]
Generate an isofill plot given the data, isofill graphics method, and

template. If no isofill object is given, then the ‘default’ isofill graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('isofill') # Show all isofill graphics methods
*******************Isofill Names List**********************
...
*******************End Isofill Names List**********************
>>> iso=a.getisofill('quick') # Create instance of 'quick'
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data file
>>> slab = f('clt') # use data file to create a cdms2 slab
>>> a.isofill(slab,iso) # Plot slab with iso; default template
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> t = a.gettemplate('hovmuller')
>>> a.isofill(slab,iso,t) # Plot with 'hovmuller' template
<vcs.displayplot.Dp ...>
Parameters
  • xaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -1 dim axis. (keyword parameter)

  • yaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -2 dim axis, only if slab has more than 1D. (keyword parameter)

  • zaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -3 dim axis, only if slab has more than 2D. (keyword parameter)

  • taxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -4 dim axis, only if slab has more than 3D. (keyword parameter)

  • waxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -5 dim axis, only if slab has more than 4D. (keyword parameter)

  • xrev (bool) – reverse x axis. (keyword parameter)

  • yrev (bool) – reverse y axis, only if slab has more than 1D. (keyword parameter)

  • xarray (array) – Values to use instead of x axis. (keyword parameter)

  • yarray (array) – Values to use instead of y axis, only if var has more than 1D. (keyword parameter)

  • zarray (array) – Values to use instead of z axis, only if var has more than 2D. (keyword parameter)

  • tarray (array) – Values to use instead of t axis, only if var has more than 3D. (keyword parameter)

  • warray (array) – Values to use instead of w axis, only if var has more than 4D. (keyword parameter)

  • continents (int) – continents type number. (keyword parameter)

  • name (str) – replaces variable name on plot. (keyword parameter)

  • time (A cdtime object) – replaces time name on plot. (keyword parameter)

  • units (str) – replaces units value on plot. (keyword parameter)

  • ymd (str) – replaces year/month/day on plot. (keyword parameter)

  • hms (str) – replaces hh/mm/ss on plot. (keyword parameter)

  • file_comment (str) – replaces file_comment on plot. (keyword parameter)

  • xbounds (array) – Values to use instead of x axis bounds values. (keyword parameter)

  • ybounds (array) – Values to use instead of y axis bounds values (if exist). (keyword parameter)

  • xname (str) – replace xaxis name on plot. (keyword parameter)

  • yname (str) – replace yaxis name on plot (if exists). (keyword parameter)

  • zname (str) – replace zaxis name on plot (if exists). (keyword parameter)

  • tname (str) – replace taxis name on plot (if exists). (keyword parameter)

  • wname (str) – replace waxis name on plot (if exists). (keyword parameter)

  • xunits (str) – replace xaxis units on plot. (keyword parameter)

  • yunits (str) – replace yaxis units on plot (if exists). (keyword parameter)

  • zunits (str) – replace zaxis units on plot (if exists). (keyword parameter)

  • tunits (str) – replace taxis units on plot (if exists). (keyword parameter)

  • wunits (str) – replace waxis units on plot (if exists). (keyword parameter)

  • xweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • yweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • comment1 (str) – replaces comment1 on plot. (keyword parameter)

  • comment2 (str) – replaces comment2 on plot. (keyword parameter)

  • comment3 (str) – replaces comment3 on plot. (keyword parameter)

  • comment4 (str) – replaces comment4 on plot. (keyword parameter)

  • long_name (str) – replaces long_name on plot. (keyword parameter)

  • grid (cdms2.grid.TransientRectGrid) – replaces array grid (if exists). (keyword parameter)

  • bg (bool/int) – plots in background mode. (keyword parameter)

  • ratio () – sets the y/x ratio ,if passed as a string with ‘t’ at the end, will aslo moves the ticks. (keyword parameter)

  • xaxisconvert (str) – (Ex: ‘linear’) converting xaxis linear/log/log10/ln/exp/area_wt

  • yaxisconvert (str) – (Ex: ‘linear’) converting yaxis linear/log/log10/ln/exp/area_wt

  • slab (array) – (Ex: [[0, 1]]) Data at least 2D, last 2 dimensions will be plotted

Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

isoline(*args, **parms)[source]
Generate a isoline plot given the data, isoline graphics method, and

template. If no isoline object is given, then the ‘default’ isoline graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('isoline') # Show all the existing isoline graphics methods
*******************Isoline Names List**********************
...
*******************End Isoline Names List**********************
>>> iso=a.getisoline('quick') # Create instance of 'quick'
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.isoline(array,iso) # Plot array using specified iso and default template
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> template = a.gettemplate('hovmuller')
>>> a.isoline(array,iso,template)  # Plot array using specified iso and template
<vcs.displayplot.Dp ...>
Parameters
  • xaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -1 dim axis. (keyword parameter)

  • yaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -2 dim axis, only if slab has more than 1D. (keyword parameter)

  • zaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -3 dim axis, only if slab has more than 2D. (keyword parameter)

  • taxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -4 dim axis, only if slab has more than 3D. (keyword parameter)

  • waxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -5 dim axis, only if slab has more than 4D. (keyword parameter)

  • xrev (bool) – reverse x axis. (keyword parameter)

  • yrev (bool) – reverse y axis, only if slab has more than 1D. (keyword parameter)

  • xarray (array) – Values to use instead of x axis. (keyword parameter)

  • yarray (array) – Values to use instead of y axis, only if var has more than 1D. (keyword parameter)

  • zarray (array) – Values to use instead of z axis, only if var has more than 2D. (keyword parameter)

  • tarray (array) – Values to use instead of t axis, only if var has more than 3D. (keyword parameter)

  • warray (array) – Values to use instead of w axis, only if var has more than 4D. (keyword parameter)

  • continents (int) – continents type number. (keyword parameter)

  • name (str) – replaces variable name on plot. (keyword parameter)

  • time (A cdtime object) – replaces time name on plot. (keyword parameter)

  • units (str) – replaces units value on plot. (keyword parameter)

  • ymd (str) – replaces year/month/day on plot. (keyword parameter)

  • hms (str) – replaces hh/mm/ss on plot. (keyword parameter)

  • file_comment (str) – replaces file_comment on plot. (keyword parameter)

  • xbounds (array) – Values to use instead of x axis bounds values. (keyword parameter)

  • ybounds (array) – Values to use instead of y axis bounds values (if exist). (keyword parameter)

  • xname (str) – replace xaxis name on plot. (keyword parameter)

  • yname (str) – replace yaxis name on plot (if exists). (keyword parameter)

  • zname (str) – replace zaxis name on plot (if exists). (keyword parameter)

  • tname (str) – replace taxis name on plot (if exists). (keyword parameter)

  • wname (str) – replace waxis name on plot (if exists). (keyword parameter)

  • xunits (str) – replace xaxis units on plot. (keyword parameter)

  • yunits (str) – replace yaxis units on plot (if exists). (keyword parameter)

  • zunits (str) – replace zaxis units on plot (if exists). (keyword parameter)

  • tunits (str) – replace taxis units on plot (if exists). (keyword parameter)

  • wunits (str) – replace waxis units on plot (if exists). (keyword parameter)

  • xweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • yweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • comment1 (str) – replaces comment1 on plot. (keyword parameter)

  • comment2 (str) – replaces comment2 on plot. (keyword parameter)

  • comment3 (str) – replaces comment3 on plot. (keyword parameter)

  • comment4 (str) – replaces comment4 on plot. (keyword parameter)

  • long_name (str) – replaces long_name on plot. (keyword parameter)

  • grid (cdms2.grid.TransientRectGrid) – replaces array grid (if exists). (keyword parameter)

  • bg (bool/int) – plots in background mode. (keyword parameter)

  • ratio () – sets the y/x ratio ,if passed as a string with ‘t’ at the end, will aslo moves the ticks. (keyword parameter)

  • xaxisconvert (str) – (Ex: ‘linear’) converting xaxis linear/log/log10/ln/exp/area_wt

  • yaxisconvert (str) – (Ex: ‘linear’) converting yaxis linear/log/log10/ln/exp/area_wt

  • slab (array) – (Ex: [[0, 1]]) Data at least 2D, last 2 dimensions will be plotted

Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

isopened()[source]

Returns a boolean value indicating whether the canvas is opened or not.

Example
>>> a=vcs.init()
>>> a.isopened() # canvas defaults to being closed
False
>>> array=[range(10) for _ in range(10)]
>>> a.plot(array)
<vcs.displayplot.Dp object at 0x...>
>>> a.isopened() # plotting opened the canvas
True
Returns

A boolean value indicating whether the Canvas is opened (1), or closed (0)

Return type

bool

isportrait()[source]

Indicates if VCS’s orientation is portrait.

Example
>>> a=vcs.init()
>>> array = [range(10) for _ in range(10)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> if a.isportrait():
...     a.landscape() # Set VCS's orientation to landscape mode
Returns

Returns a 1 if orientation is portrait, or 0 if not in portrait mode

Return type

bool

landscape(width=-99, height=-99, x=-99, y=-99, clear=0)[source]

Change the VCS Canvas orientation to Landscape.

Note

The (width, height) and (x, y) arguments work in pairs. That is, you must set (width, height) or (x, y) together to see any change in the VCS Canvas.

If the portrait method is called with arguments before displaying a VCS Canvas, then the arguments (width, height, x, y, and clear) will have no effect on the canvas.

Warning

If the visible plot on the VCS Canvas is not adjusted properly, then resize the screen with the point. Some X servers are not handling the threads properly to keep up with the demands of the X client.

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.landscape() # Change the VCS Canvas orientation and set object flag to landscape
>>> a.landscape(clear=1) # Change the VCS Canvas to landscape and clear the page
>>> a.landscape(width = 400, height = 337) # Change to landscape and set the window size
>>> a.landscape(x=100, y = 200) # Change to landscape and set the x and y screen position
>>> a.landscape(width = 400, height = 337, x=100, y = 200, clear=1) # landscape with more settings
Parameters
  • width (int) – Width of the canvas, in pixels

  • height (int) – Height of the canvas, in pixels

  • x (int) – Unused

  • y (int) – Unused

  • clear (int) – Indicates the canvas should be cleared (1), or should not be cleared (0), when orientation is changed.

line(*args, **parms)[source]

Plot a line segment on the Vcs Canvas. If no line class object is given, then an error will be returned.

Example
>>> a=vcs.init()
>>> a.show('line')  # Show all the existing line objects
*******************Line Names List**********************
...
*******************End Line Names List**********************
>>> ln=a.getline('red') # Create instance of 'red'
>>> ln.width=4 # Set the line width
>>> ln.color = 242 # Set the line color
>>> ln.type = 4 # Set the line type
>>> ln.x=[[0.0,2.0,2.0,0.0,0.0], [0.5,1.5]] # Set the x value points
>>> ln.y=[[0.0,0.0,2.0,2.0,0.0], [1.0,1.0]] # Set the y value points
>>> a.line(ln) # Plot using specified line object
<vcs.displayplot.Dp ...>
Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

listelements(*args)[source]

Returns a sorted Python list of all VCS object names, or a list of names of objects of the given type.

Example
>>> a=vcs.init()
>>> a.listelements()
['1d', '3d_dual_scalar', '3d_scalar', ...]
Parameters

args (str or None) – A string containing the name of a VCS object type, or None

Returns

If args is None, returns a list of string names of all VCS objects. If args is a string name of a VCS object

Return type

list

marker(*args, **parms)[source]

Plot a marker segment on the Vcs Canvas. If no marker class object is given, then an error will be returned.

Example
>>> a=vcs.init()
>>> a.show('marker') # Show all the existing marker objects
*******************Marker Names List**********************
...
*******************End Marker Names List**********************
>>> mrk=a.getmarker('red') # Create instance of 'red'
>>> mrk.size=4 # Set the marker size
>>> mrk.color = 242 # Set the marker color
>>> mrk.type = 4 # Set the marker type
>>> mrk.x=[[0.0,2.0,2.0,0.0,0.0], [0.5,1.5]] # Set the x value points
>>> mrk.y=[[0.0,0.0,2.0,2.0,0.0], [1.0,1.0]] # Set the y value points
>>> a.marker(mrk) # Plot using specified marker object
<vcs.displayplot.Dp ...>
Returns

a VCS displayplot object

Return type

vcs.displayplot.Dp

match_color(color, colormap=None)[source]

Returns the color in the colormap that’s closest to the specified color.

Example
>>> a=vcs.init()
>>> print(vcs.match_color('salmon', 'magma'))
192
>>> print(vcs.match_color('red', 'rainbow'))
242
>>> print(vcs.match_color([0,0,100],'default')) # closest color from blue
52
Parameters
  • color (str or int) – Either a string name, or a rgb value between 0 and 100.

  • colormap (vcs.colormap.Cp) – A VCS colormap object. If not specified, the default colormap is used.

Returns

Integer value representing a matching rgb color

Return type

int

meshfill(*args, **parms)[source]

Generate a meshfill plot given the data, the mesh, a meshfill graphics method, and a template. If no meshfill object is given, then the ‘default’ meshfill graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Format: This function expects 1D data (any extra dimension will be used for animation) In addition the mesh array must be of the same shape than data with 2 additional dimension representing the vertices coordinates for the Y (0) and X (1) dimension Let’s say you want to plot a spatial assuming mesh containing 10,000 grid cell, then data must be shape (10000,) or (n1,n2,n3,…,10000) if additional dimensions exist (ex time,level), these dimensions would be used only for animation and will be ignored in the rest of this example. The shape of the mesh, assuming 4 vertices per grid cell, must be (1000,2,4), where the array [:,0,:] represent the Y coordinates of the vertices (clockwise or counterclockwise) and the array [:,1:] represents the X coordinates of the vertices (the same clockwise/counterclockwise than the Y coordinates) In brief you’d have: data.shape=(10000,) mesh.shape=(10000,2,4)

Example
>>> a=vcs.init()
>>> a.show('meshfill') # Show all meshfill graphics methods
*******************Meshfill Names List**********************
...
*******************End Meshfill Names List**********************
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file
>>> slab = f('clt') # use data file to create a cdms2 slab
>>> m=a.getmeshfill() # Create instance of 'default'
>>> a.meshfill(slab,m) # Plot with default mesh & template
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> p='a_polar_meshfill' # will use this to plot
>>> a.meshfill(slab,m,'quick', p) # polar mesh, quick template
<vcs.displayplot.Dp ...>
Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

objecthelp(*arg)[source]

Print out information on the VCS object. See example below on its use.

Example
>>> a=vcs.init()
>>> ln=a.getline('red') # Get a VCS line object
>>> a.objecthelp(ln) # This will print out information on how to use ln
The Line object ...
open(width=None, height=None, **kargs)[source]

Open VCS Canvas object. This routine really just manages the VCS canvas. It can be used to display the VCS Canvas.

Example
>>> a=vcs.init()
>>> a.open()
>>> a.open(800,600)
Parameters
  • width (int) – Width of the canvas, in pixels

  • height (int) – Height of the canvas, in pixels

orientation(*args, **kargs)[source]

Return canvas orientation.

The current implementation does not use any args or kargs.

Example
>>> a=vcs.init()
>>> a.orientation() # Show current orientation of the canvas
'landscape'
Returns

A string indicating the orientation of the canvas, i.e. ‘landscape’ or ‘portrait’

Return type

str

pdf(file, width=None, height=None, units='inches', textAsPaths=True)[source]

PDF output is another form of vector graphics.

Note

The textAsPaths parameter preserves custom fonts, but text can no longer be edited in the file

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.pdf('example') # Overwrite a postscript file
>>> a.pdf('example', width=11.5, height= 8.5) # US Legal
>>> a.pdf('example', width=21, height=29.7, units='cm') # A4
Parameters
  • file (str) – Desired string name of the output file

  • width (float) – Float specifying the desired width of the output, in the specified unit of measurement.

  • height (float) – Float specifying the desired height of the output, measured in the chosen units

  • units (str) – One of [‘inches’, ‘in’, ‘cm’, ‘mm’, ‘pixel’, ‘pixels’, ‘dot’, ‘dots’]. Defaults to ‘inches’.

  • textAsPaths (bool) – Specifies whether to render text objects as paths.

plot(*actual_args, **keyargs)[source]

Plot an array(s) of data given a template and graphics method.

The VCS template is used to define where the data and variable attributes will be displayed on the VCS Canvas.

The VCS graphics method is used to define how the array(s) will be shown on the VCS Canvas.

Plot Usage:
>>> import numpy
>>> a=vcs.init()
>>> a.show('template') # list vcs template types
*******************Template Names List**********************
...
*******************End Template Names List**********************
>>> a.show('boxfill') # one of many graphics method types
*******************Boxfill Names List**********************
...
*******************End Boxfill Names List**********************
>>> array1 = numpy.array([range(10) for _ in range(10)]) # data
>>> a.plot(variable=array1)
<vcs.displayplot.Dp ...>
>>> a.plot(array1,'ASD',gm='boxfill')  # boxfill, ASD template
<vcs.displayplot.Dp ...>
Plot attribute keywords:

Note

Attribute Precedence

Specific attributes take precedence over general attributes. In particular, specific attributes override variable object attributes, dimension attributes and arrays override axis objects, which override grid objects, which override variable objects.

For example, if both ‘file_comment’ and ‘variable’ keywords are specified, the value of ‘file_comment’ is used instead of the file comment in the parent of variable. Similarly, if both ‘xaxis’ and ‘grid’ keywords are specified, the value of ‘xaxis’ takes precedence over the x-axis of grid.

  • ratio [default is None]

    • None: let the self.ratio attribute decide

    • 0, ‘off’: overwrite self.ratio and do nothing about the ratio

    • ‘auto’: computes an automatic ratio

    • ‘3’, 3: y dim will be 3 times bigger than x dim (restricted

      to original template.data area)

    • Adding a ‘t’ at the end of the ratio, makes the tickmarks and

      boxes move along.

  • Dimension attribute keys (dimension length=n):

    • x or y Dimension values

      [x|y|z|t|w]array = NumPy array of length n
      [x|y|z|t|w]array = NumPy array of length n
      
    • x or y Dimension boundaries

      [x|y]bounds = NumPy array of shape (n,2)
      
  • CDMS object:

    • x or y Axis

      [x|y|z|t|w]axis = CDMS axis object
      
    • Grid object (e.g. grid=var.getGrid())

      grid = CDMS grid object
      
    • Variable object

      variable = CDMS variable object
      
  • Other:

    • Reverse the direction of the x or y axis:

      [x|y]rev = 0|1
      

      Note

      For example, xrev = 1 would reverse the direction of the x-axis

    • Continental outlines:

      continents = 0,1,2,3,4,5,6,7,8,9,10,11
      # VCS line object to define continent appearance
      continents_line = vcs.getline("default")
      

      Note

      If continents >=1, plot continental outlines. By default: plot of xaxis is longitude, yaxis is latitude -OR- xname is ‘longitude’ and yname is ‘latitude’

      • List of continents-type values (integers from 0-11)

        • 0 signifies “No Continents”

        • 1 signifies “Fine Continents”

        • 2 signifies “Coarse Continents”

        • 3 signifies “United States”

        • 4 signifies “Political Borders”

        • 5 signifies “Rivers”

      Note

      Values 6 through 11 signify the line type defined by the files data_continent_other7 through data_continent_other12.

    • To set whether the displayplot object generated by this plot is stored

      donotstoredisplay = True|False
      
    • Whether to actually render the plot or not (useful for doing a bunch of plots in a row)

      render = True|False
      
    • VCS Display plot name (used to prevent duplicate display plots)

      display_name = "__display_123"
      
    • Ratio of height/width for the plot; autot and auto will choose a “good” ratio for you.

      ratio = 1.5|"autot"|"auto"
      
    • Plot the actual grid or the dual grid

      plot_based_dual_grid = True | False
      

      Note

      This is based on what is needed by the plot: isofill, isoline, vector need point attributes, boxfill and meshfill need cell attributes the default is True (if the parameter is not specified).

    • Graphics Output in Background Mode:

      # if 1, create images in the background (not on canvas)
      bg = 0|1
      
Example
>>> a=vcs.init()
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file
>>> slab1 = f('u') # use the data file to create a cdms2 slab
>>> slab2 = f('v') # need 2 slabs, so get another
>>> a.plot(slab1) # default settings for template and boxfill
<vcs.displayplot.Dp ...>
>>> a.plot(slab1,'polar','isofill','polar') # specify template and graphics method
<vcs.displayplot.Dp ...>
>>> t=a.gettemplate('polar') # get the polar template
>>> vec=a.getvector() # get default vector
>>> a.plot(slab1, slab2, t, vec) # plot data as vector using polar template
<vcs.displayplot.Dp ...>
>>> a.clear() # clear the VCS Canvas of all plots
>>> box=a.getboxfill() # get default boxfill graphics method
>>> a.plot(box,t,slab2) # plot data with boxfill and polar
<vcs.displayplot.Dp ...>
Parameters
  • slab2 (array) – Data at least 1D, last dimension(s) will be plotted

  • template (str/vcs.template.P) – (‘default’) vcs template to use

  • gm (VCS graphics method object) – (Ex: ‘default’) graphic method to use

  • xaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -1 dim axis. (keyword parameter)

  • yaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -2 dim axis, only if slab has more than 1D. (keyword parameter)

  • zaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -3 dim axis, only if slab has more than 2D. (keyword parameter)

  • taxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -4 dim axis, only if slab has more than 3D. (keyword parameter)

  • waxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -5 dim axis, only if slab has more than 4D. (keyword parameter)

  • xrev (bool) – reverse x axis. (keyword parameter)

  • yrev (bool) – reverse y axis, only if slab has more than 1D. (keyword parameter)

  • xarray (array) – Values to use instead of x axis. (keyword parameter)

  • yarray (array) – Values to use instead of y axis, only if var has more than 1D. (keyword parameter)

  • zarray (array) – Values to use instead of z axis, only if var has more than 2D. (keyword parameter)

  • tarray (array) – Values to use instead of t axis, only if var has more than 3D. (keyword parameter)

  • warray (array) – Values to use instead of w axis, only if var has more than 4D. (keyword parameter)

  • continents (int) – continents type number. (keyword parameter)

  • name (str) – replaces variable name on plot. (keyword parameter)

  • time (A cdtime object) – replaces time name on plot. (keyword parameter)

  • units (str) – replaces units value on plot. (keyword parameter)

  • ymd (str) – replaces year/month/day on plot. (keyword parameter)

  • hms (str) – replaces hh/mm/ss on plot. (keyword parameter)

  • file_comment (str) – replaces file_comment on plot. (keyword parameter)

  • xbounds (array) – Values to use instead of x axis bounds values. (keyword parameter)

  • ybounds (array) – Values to use instead of y axis bounds values (if exist). (keyword parameter)

  • xname (str) – replace xaxis name on plot. (keyword parameter)

  • yname (str) – replace yaxis name on plot (if exists). (keyword parameter)

  • zname (str) – replace zaxis name on plot (if exists). (keyword parameter)

  • tname (str) – replace taxis name on plot (if exists). (keyword parameter)

  • wname (str) – replace waxis name on plot (if exists). (keyword parameter)

  • xunits (str) – replace xaxis units on plot. (keyword parameter)

  • yunits (str) – replace yaxis units on plot (if exists). (keyword parameter)

  • zunits (str) – replace zaxis units on plot (if exists). (keyword parameter)

  • tunits (str) – replace taxis units on plot (if exists). (keyword parameter)

  • wunits (str) – replace waxis units on plot (if exists). (keyword parameter)

  • xweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • yweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • comment1 (str) – replaces comment1 on plot. (keyword parameter)

  • comment2 (str) – replaces comment2 on plot. (keyword parameter)

  • comment3 (str) – replaces comment3 on plot. (keyword parameter)

  • comment4 (str) – replaces comment4 on plot. (keyword parameter)

  • long_name (str) – replaces long_name on plot. (keyword parameter)

  • grid (cdms2.grid.TransientRectGrid) – replaces array grid (if exists). (keyword parameter)

  • bg (bool/int) – plots in background mode. (keyword parameter)

  • ratio () – sets the y/x ratio ,if passed as a string with ‘t’ at the end, will aslo moves the ticks. (keyword parameter)

  • xaxisconvert (str) – (Ex: ‘linear’) converting xaxis linear/log/log10/ln/exp/area_wt

  • yaxisconvert (str) – (Ex: ‘linear’) converting yaxis linear/log/log10/ln/exp/area_wt

  • slab_or_primary_object (array) – Data at least 1D, last dimension(s) will be plotted, or secondary vcs object

Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

returns

A VCS display plot object

rtype

vcs.displayplot.Dp

png(file, width=None, height=None, units=None, draw_white_background=True, provenance=False, **args)[source]

PNG output, dimensions set via setbgoutputdimensions

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.png('example') # Overwrite a png file
Parameters
  • file (str) – Desired string name of the output file

  • width (float) – Float specifying the desired width of the output, in the specified unit of measurement.

  • height (float) – Float specifying the desired height of the output, measured in the chosen units

  • units (str) – One of [‘inches’, ‘in’, ‘cm’, ‘mm’, ‘pixel’, ‘pixels’, ‘dot’, ‘dots’]. Defaults to ‘inches’.

  • draw_white_background (bool) – Boolean value indicating if the background should be white. Defaults to True.

portrait(width=-99, height=-99, x=-99, y=-99, clear=0)[source]

Change the VCS Canvas orientation to Portrait.

Note

If the current orientation of the canvas is already portrait, nothing happens.

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.portrait()  # Change the VCS Canvas orientation and set object flag to portrait
>>> a.portrait(clear=1) # Change the VCS Canvas to portrait and clear the page
>>> a.portrait(width = 337, height = 400) # Change to portrait and set the window size
>>> a.portrait(x=100, y = 200) # Change to portrait and set the x and y screen position
>>> a.portrait(width = 337, height = 400, x=100, y = 200, clear=1) # portrait, with more specifications
Parameters
  • width (int) – Width of the canvas, in pixels

  • height (int) – Height of the canvas, in pixels

  • x (None) – Unused.

  • y (None) – Unused.

  • clear (int) – Indicates the canvas should be cleared (1), or should not be cleared (0), when orientation is changed.

postscript(file, mode='r', orientation=None, width=None, height=None, units='inches', textAsPaths=True)[source]

Postscript output is another form of vector graphics. It is larger than its CGM output counter part, because it is stored out in ASCII format.

There are two modes for saving a postscript file: ‘Append’ (a) mode appends postscript output to an existing postscript file; and ‘Replace’ (r) mode overwrites an existing postscript file with new postscript output. The default mode is to overwrite an existing postscript file.

Note

The textAsPaths parameter preserves custom fonts, but text can no longer be edited in the file

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.postscript('example') # Overwrite a postscript file
>>> a.postscript('example', 'a') # Append postscript to an existing file
>>> a.postscript('example', 'r') # Overwrite an existing file
>>> a.postscript('example', mode='a') # Append postscript to an existing file
>>> a.postscript('example', width=11.5, height= 8.5) # US Legal (default)
>>> a.postscript('example', width=21, height=29.7, units='cm') # A4
Parameters
  • file (str) – Desired string name of the output file

  • mode (str) – The mode in which to open the file. One of ‘r’ or ‘a’. When mode is ‘r’, file will be opened in replace mode. When mode is ‘a’, file will be opened in append mode.

  • width (float) – Float specifying the desired width of the output, in the specified unit of measurement.

  • height (float) – Float specifying the desired height of the output, measured in the chosen units

  • units (str) – One of [‘inches’, ‘in’, ‘cm’, ‘mm’, ‘pixel’, ‘pixels’, ‘dot’, ‘dots’]. Defaults to ‘inches’.

  • textAsPaths (bool) – Specifies whether to render text objects as paths.

put_png_on_canvas(filename, zoom=1, xOffset=0, yOffset=0, units='percent', fitToHeight=True, *args, **kargs)[source]

Display a PNG file on the canvas

Example
>>> a=vcs.init()
>>> array=[range(10) for i in range(10)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.png("bars.png") # make a png named 'bars.png'
>>> a.clear() # clear the bars off the canvas
>>> a.put_png_on_canvas("bars.png") # put 'bars.png' on canvas
Parameters
  • file (str) – Input image filename

  • zoom (int) – scale factor

  • xOffset (float) – Horizontal Offset

  • yOffset (float) – Vertical Offset

  • units (str) – Specifies the units used for x and y Offsets. One of [‘percent’,’pixels’].

  • fitToHeight (bool) – If True, fits the picture (before scaling) to the canvas full height, if False then use png original size.

raisecanvas(*args)[source]

Raise the VCS Canvas to the top of all open windows.

Example
>>> a=vcs.init()
>>> a.open()
>>> a.raisecanvas() # canvas should now be at the top
remove_display_name(*args)[source]

Removes a plotted item from the canvas.

Example
>>> a=vcs.init()
>>> a.return_display_names() # new canvas should have none
[]
>>> array=[range(10) for _ in range(10)]
>>> plot=a.plot(array) # store plot for reference to plot name
>>> a.return_display_names() # has display name for new plot
[...]
>>> a.remove_display_name(plot.name)
>>> a.return_display_names() # should be empty again
[]
Parameters

args (list of str) – Any number of display names to remove.

removeobject(obj)[source]

The user has the ability to create primary and secondary class objects. The function allows the user to remove these objects from the appropriate class list.

Note

The user is not allowed to remove a “default” class object.

Example
>>> a=vcs.init()
>>> iso=a.createisoline('dean') # Create an instance of an isoline object
>>> a.removeobject(iso) # Remove isoline object from VCS list
'Removed isoline object dean'
Parameters

obj (VCS object) – Any VCS primary or secondary object

Returns

String indicating the specified object was removed

Return type

str

return_display_names(*args)[source]

Show the list of display names associated with all active plots on the canvas.

Example
>>> a=vcs.init()
>>> a.return_display_names() # new canvas should have none
[]
>>> array=[range(10) for _ in range(10)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.return_display_names() # has display name for new plot
[...]
Returns

A list of the display names of images currently plotted on the canvas.

Return type

list

saveinitialfile()[source]

At start-up, VCS reads a script file named initial.attributes that defines the initial appearance of the VCS Interface. Although not required to run VCS, this initial.attributes file contains many predefined settings to aid the beginning user of VCS.

Example
a=vcs.init()
box=vcs.createboxfill('m_box')
line=vcs.createline('m_line')
a.saveinitialfile() # m_line, m_box saved for future sessions

Warning

This removes first ALL objects generated automatically (i.e. whose name starts with ‘__’). To preserve these, rename objects first e.g.:

>>> b=vcs.createboxfill()
>>> b.rename('MyBoxfill') # graphic method is now preserved
scalar3d(*args, **parms)[source]

Generate a 3d_scalar plot given the data, 3d_scalar graphics method, and template. If no 3d_scalar object is given, then the ‘default’ 3d_scalar graphics method is used. Similarly, if no template is given, the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('3d_scalar') # Show all 3d_scalars
*******************3d_scalar Names List**********************
...
*******************End 3d_scalar Names List**********************
>>> ds=a.get3d_scalar() # default 3d_scalar
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data file
>>> s = f('clt') # use data file to create a cdms2 slab
>>> # Plot slab with defaults
>>> a.scalar3d(ds, s) 
initCamera: Camera => (...)
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> t = a.gettemplate('polar')
>>> # Plot with 'polar' template
>>> a.scalar3d(s, ds, t)  
initCamera: Camera => (...)
<vcs.displayplot.Dp ...>
scatter(*args, **parms)[source]
Generate a scatter plot given the data, scatter graphics method, and

template. If no scatter object is given, then the ‘default’ scatter graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('scatter') # Show all the existing scatter graphics methods
*******************Scatter Names List**********************
...
*******************End Scatter Names List**********************
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # use cdms2 to open a data file
>>> slab1 = f('u') # use the data file to create a cdms2 slab
>>> slab2 = f('v') # need 2 slabs, so get another
>>> a.scatter(slab1, slab2) # Plot array using specified sct and default template
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> template=a.gettemplate('hovmuller')
>>> a.scatter(slab1, slab2, template) # Plot array using specified sct and template
<vcs.displayplot.Dp ...>
Parameters
  • xaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -1 dim axis. (keyword parameter)

  • yaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -2 dim axis, only if slab has more than 1D. (keyword parameter)

  • zaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -3 dim axis, only if slab has more than 2D. (keyword parameter)

  • taxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -4 dim axis, only if slab has more than 3D. (keyword parameter)

  • waxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -5 dim axis, only if slab has more than 4D. (keyword parameter)

  • xrev (bool) – reverse x axis. (keyword parameter)

  • yrev (bool) – reverse y axis, only if slab has more than 1D. (keyword parameter)

  • xarray (array) – Values to use instead of x axis. (keyword parameter)

  • yarray (array) – Values to use instead of y axis, only if var has more than 1D. (keyword parameter)

  • zarray (array) – Values to use instead of z axis, only if var has more than 2D. (keyword parameter)

  • tarray (array) – Values to use instead of t axis, only if var has more than 3D. (keyword parameter)

  • warray (array) – Values to use instead of w axis, only if var has more than 4D. (keyword parameter)

  • continents (int) – continents type number. (keyword parameter)

  • name (str) – replaces variable name on plot. (keyword parameter)

  • time (A cdtime object) – replaces time name on plot. (keyword parameter)

  • units (str) – replaces units value on plot. (keyword parameter)

  • ymd (str) – replaces year/month/day on plot. (keyword parameter)

  • hms (str) – replaces hh/mm/ss on plot. (keyword parameter)

  • file_comment (str) – replaces file_comment on plot. (keyword parameter)

  • xbounds (array) – Values to use instead of x axis bounds values. (keyword parameter)

  • ybounds (array) – Values to use instead of y axis bounds values (if exist). (keyword parameter)

  • xname (str) – replace xaxis name on plot. (keyword parameter)

  • yname (str) – replace yaxis name on plot (if exists). (keyword parameter)

  • zname (str) – replace zaxis name on plot (if exists). (keyword parameter)

  • tname (str) – replace taxis name on plot (if exists). (keyword parameter)

  • wname (str) – replace waxis name on plot (if exists). (keyword parameter)

  • xunits (str) – replace xaxis units on plot. (keyword parameter)

  • yunits (str) – replace yaxis units on plot (if exists). (keyword parameter)

  • zunits (str) – replace zaxis units on plot (if exists). (keyword parameter)

  • tunits (str) – replace taxis units on plot (if exists). (keyword parameter)

  • wunits (str) – replace waxis units on plot (if exists). (keyword parameter)

  • xweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • yweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • comment1 (str) – replaces comment1 on plot. (keyword parameter)

  • comment2 (str) – replaces comment2 on plot. (keyword parameter)

  • comment3 (str) – replaces comment3 on plot. (keyword parameter)

  • comment4 (str) – replaces comment4 on plot. (keyword parameter)

  • long_name (str) – replaces long_name on plot. (keyword parameter)

  • grid (cdms2.grid.TransientRectGrid) – replaces array grid (if exists). (keyword parameter)

  • bg (bool/int) – plots in background mode. (keyword parameter)

  • ratio () – sets the y/x ratio ,if passed as a string with ‘t’ at the end, will aslo moves the ticks. (keyword parameter)

  • xaxisconvert (str) – (Ex: ‘linear’) converting xaxis linear/log/log10/ln/exp/area_wt

  • yaxisconvert (str) – (Ex: ‘linear’) converting yaxis linear/log/log10/ln/exp/area_wt

  • slab_or_primary_object (array) – Data at least 1D, last dimension(s) will be plotted, or secondary vcs object

Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

scriptobject(obj, script_filename=None, mode=None)[source]

Save individual attributes sets (i.e., individual primary class objects and/or secondary objects). These attribute sets are saved in the user’s current directory in one of two formats: Python script, or a Javascript Object.

Note

If the the filename has a “.py” at the end, it will produce a Python script. If the filename has a “.scr” at the end, it will produce a VCS script. If neither extensions are given, then by default a Javascript Object will be produced.

Attention

VCS does not allow the modification of ‘default’ attribute sets, it will not allow them to be saved as individual script files. However, a ‘default’ attribute set that has been copied under a different name can be saved as a script file.

VCS Scripts Deprecated

SCR scripts are no longer generated by this function

Example
>>> a=vcs.init()
>>> i=a.createisoline('dean') # default isoline object instance
>>> a.scriptobject(i,'ex_isoline.py') # Save to 'isoline.py'
>>> a.scriptobject(i,'ex_isoline2') # Save to 'isoline2.json'
Parameters
  • script_filename (str) – Name of the output script file.

  • mode (str) – Mode is either “w” for replace or “a” for append.

  • obj (VCS object) – Any VCS primary class or secondary object.

scriptrun(aFile, *args, **kargs)[source]

Given the path to a script containing a VCS object, scriptrun runs that script to build the object.

Example
>>> b=vcs.createboxfill('new_box')
>>> b.script('new_box') # json representation of 'new_box'
>>> bfs=vcs.listelements('boxfill') # list all boxfills
>>> i=bfs.index('new_box')
>>> bfs[i] # shows 'new_box' exists
'new_box'
>>> vcs.removeobject(b) # remove new_box
'Removed boxfill object new_box'
>>> bfs=vcs.listelements('boxfill') # list all boxfills
>>> try:
...     bfs.index('new_box')
... except Exception:
...     print ("boxfill 'new_box' doesn't exist")
boxfill 'new_box' doesn't exist
>>> vcs.scriptrun('new_box.json') # re-creates 'new_box'
>>> bfs=vcs.listelements('boxfill') # list all boxfills
>>> i=bfs.index('new_box')
>>> bfs[i]  # shows 'new_box' exists (again)
'new_box'
Parameters

aFile (str) – String representing the path to a the script.

setantialiasing(antialiasing)[source]

Sets the antialiasing rate for the canvas.

Example
>>> a=vcs.init()
>>> a.setantialiasing(20)
>>> a.getantialiasing()
20
Parameters

antialiasing (int) – Integer from 0-64, representing the antialising rate (0 means no antialiasing).

setbgoutputdimensions(width=None, height=None, units='inches')[source]

Sets dimensions for output in bg mode.

Example
>>> a=vcs.init()
>>> a.setbgoutputdimensions(width=11.5, height= 8.5) # US Legal
>>> a.setbgoutputdimensions(width=21, height=29.7, units='cm') # A4
Parameters
  • width (float) – Float specifying the desired width of the output, in the specified unit of measurement.

  • height (float) – Float specifying the desired height of the output, measured in the chosen units

  • units (str) – One of [‘inches’, ‘in’, ‘cm’, ‘mm’, ‘pixel’, ‘pixels’, ‘dot’, ‘dots’]. Defaults to ‘inches’.

setcolorcell(*args)[source]

Set a individual color cell in the active colormap. If default is the active colormap, then return an error string.

If the the visul display is 16-bit, 24-bit, or 32-bit TrueColor, then a redrawing of the VCS Canvas is made evertime the color cell is changed.

Note, the user can only change color cells 0 through 239 and R,G,B value must range from 0 to 100. Where 0 represents no color intensity and 100 is the greatest color intensity.

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
>>> a.setcolormap("AMIP")
>>> a.setcolorcell(11,0,0,0)
>>> a.setcolorcell(21,100,0,0)
>>> a.setcolorcell(31,0,100,0)
>>> a.setcolorcell(41,0,0,100)
>>> a.setcolorcell(51,100,100,100)
>>> a.setcolorcell(61,70,70,70)
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
setcolormap(name)[source]

It is necessary to change the colormap. This routine will change the VCS color map.

If the the visual display is 16-bit, 24-bit, or 32-bit TrueColor, then a redrawing of the VCS Canvas is made every time the colormap is changed.

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
>>> a.setcolormap("AMIP")
>>> a.plot(array,'default','isofill','quick')
<vcs.displayplot.Dp ...>
Parameters

name (str) – Name of the colormap to use

setcontinentsline(line='default')[source]

One has the option of configuring the appearance of the lines used to draw continents by providing a VCS Line object.

Example
>>> a = vcs.init()
>>> line = vcs.createline()
>>> line.width = 5
>>> a.setcontinentsline(line) # Use custom continents line
>>> a.setcontinentsline("default") # Use default line
Parameters

line (str or vcs.line.Tl) – Line to use for drawing continents. Can be a string name of a line, or a VCS line object

setdefaultfont(font)[source]

Sets the passed/def show font as the default font for vcs

Parameters

font (str or int) – Font name or index to use as default

Attention

This function does not currently work. It will be implemented in the future.

show(*args)[source]

Show the list of VCS primary and secondary class objects.

Example
>>> vcs.show() # show all vcs object types
['1d', '3d_dual_scalar', '3d_scalar', '3d_vector', 'boxfill', ...]
>>> vcs.show('boxfill') # List boxfill objects
*******************Boxfill Names List**********************
...
*******************End Boxfill Names List**********************
>>> vcs.show('3d_vector') # List 3d_vector objects
*******************3d_vector Names List**********************
...
*******************End 3d_vector Names List**********************
>>> vcs.show('3d_scalar') # List 3d_scalar objects
*******************3d_scalar Names List**********************
...
*******************End 3d_scalar Names List**********************
>>> vcs.show('3d_dual_scalar') # List 3d_dual_scalar objects
*******************3d_dual_scalar Names List**********************
...
*******************End 3d_dual_scalar Names List**********************
>>> vcs.show('1d') # List 1d objects
*******************1d Names List**********************
...
*******************End 1d Names List**********************
Parameters

args (str or None) – String name of a type of object to show, or None

streamline(*args, **parms)[source]

Generate a streamline plot given the data, streamline graphics method, and template. If no streamline class object is given, then the ‘default’ streamline graphics method is used. Similarly, if no template class object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('streamline') # Show all the existing streamline graphics methods
*******************Streamline Names List**********************
...
*******************End Streamline Names List**********************
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open a data file
>>> slab1 = f('u') # use the data file to create a cdms2 slab
>>> slab2 = f('v') # streamline needs 2 slabs, so get another
>>> # plot streamline using slab and default
>>> # streamline
>>> a.streamline(slab1, slab2)
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> template=a.gettemplate('hovmuller')
>>> # Plot array using default streamline
>>> # and specified template
>>> a.streamline(slab1, slab2, template)
<vcs.displayplot.Dp ...>
Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

svg(file, width=None, height=None, units='inches', textAsPaths=True)[source]

SVG output is another form of vector graphics.

Note

The textAsPaths parameter preserves custom fonts, but text can no longer be edited in the file

Example
>>> a=vcs.init()
>>> array = [range(1, 11) for _ in range(1, 11)]
>>> a.plot(array)
<vcs.displayplot.Dp ...>
>>> a.svg('example') # Overwrite a postscript file
>>> a.svg('example', width=11.5, height= 8.5) # US Legal
>>> a.svg('example', width=21, height=29.7, units='cm') # A4
Parameters
  • file (str) – Desired string name of the output file

  • width (float) – Float specifying the desired width of the output, in the specified unit of measurement.

  • height (float) – Float specifying the desired height of the output, measured in the chosen units

  • units (str) – One of [‘inches’, ‘in’, ‘cm’, ‘mm’, ‘pixel’, ‘pixels’, ‘dot’, ‘dots’]. Defaults to ‘inches’.

  • textAsPaths (bool) – Specifies whether to render text objects as paths.

switchfonts(font1, font2)[source]

Switch the font numbers of two fonts.

Example
>>> a=vcs.init()
>>> maths1 = a.getfontnumber('Maths1') # store font number
>>> maths2 = a.getfontnumber('Maths2') # store font number
>>> a.switchfonts('Maths1','Maths2') # switch font numbers
>>> new_maths1 = a.getfontnumber('Maths1')
>>> new_maths2 = a.getfontnumber('Maths2')
>>> maths1 == new_maths2 and maths2 == new_maths1 # check
True
Parameters
  • font1 (int or str) – The first font

  • font2 (int or str) – The second font

taylordiagram(*args, **parms)[source]

Generate a taylordiagram plot given the data, taylordiagram graphics method, and template. If no taylordiagram object is given, then the ‘default’ taylordiagram graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('taylordiagram') # Show all the existing taylordiagram graphics methods
*******************Taylordiagram Names List**********************
...
*******************End Taylordiagram Names List**********************
>>> td= a.gettaylordiagram() # Create instance of 'default'
>>> array=[range(1, 11) for _ in range(1, 11)]
>>> a.taylordiagram(array,td) # Plot array using specified iso and default template
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> template=a.gettemplate('hovmuller')
>>> a.taylordiagram(array,td,template) # Plot array using specified iso and template
<vcs.displayplot.Dp ...>
Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

text(*args, **parms)

Plot a textcombined segment on the Vcs Canvas. If no textcombined class object is given, then an error will be returned.

Example

>>> a=vcs.init()
>>> a.clean_auto_generated_objects()
>>> a.show('texttable') # Show all the existing texttable objects
*******************Texttable Names List**********************
...
*******************End Texttable Names List**********************
>>> a.show('textorientation') # Show all the existing textorientation objects
*******************Textorientation Names List**********************
...
*******************End Textorientation Names List**********************
>>> if "qa_tta" in vcs.listelements("texttable"): vcs.reset()
...
>>> if "7left_tto" in vcs.listelements("textorientation"): vcs.reset()
...
>>> vcs.createtext('qa_tta', 'qa', '7left_tto', '7left') # Create instance of 'qa_tt' and '7left_to'
<vcs.textcombined.Tc object at ...>
>>> tc=a.gettext('qa_tta', '7left_tto')
>>> tc.string='Text1' # Show the string "Text1" on the VCS Canvas
>>> tc.font=2 # Set the text size
>>> tc.color=242 # Set the text color
>>> tc.angle=45 # Set the text angle
>>> tc.x=[0.5]
>>> tc.y=[0.5]
>>> a.textcombined(tc) # Plot using specified text object
<vcs.displayplot.Dp ...>
Returns

A fillarea object

Return type

vcs.displayplot.Dp

textcombined(*args, **parms)[source]

Plot a textcombined segment on the Vcs Canvas. If no textcombined class object is given, then an error will be returned.

Example

>>> a=vcs.init()
>>> a.clean_auto_generated_objects()
>>> a.show('texttable') # Show all the existing texttable objects
*******************Texttable Names List**********************
...
*******************End Texttable Names List**********************
>>> a.show('textorientation') # Show all the existing textorientation objects
*******************Textorientation Names List**********************
...
*******************End Textorientation Names List**********************
>>> if "qa_tta" in vcs.listelements("texttable"): vcs.reset()
...
>>> if "7left_tto" in vcs.listelements("textorientation"): vcs.reset()
...
>>> vcs.createtext('qa_tta', 'qa', '7left_tto', '7left') # Create instance of 'qa_tt' and '7left_to'
<vcs.textcombined.Tc object at ...>
>>> tc=a.gettext('qa_tta', '7left_tto')
>>> tc.string='Text1' # Show the string "Text1" on the VCS Canvas
>>> tc.font=2 # Set the text size
>>> tc.color=242 # Set the text color
>>> tc.angle=45 # Set the text angle
>>> tc.x=[0.5]
>>> tc.y=[0.5]
>>> a.textcombined(tc) # Plot using specified text object
<vcs.displayplot.Dp ...>
Returns

A fillarea object

Return type

vcs.displayplot.Dp

update(*args, **kargs)[source]

If a series of commands are given to VCS and the Canvas Mode is set to manual, then use this function to update the plot(s) manually.

Example
>>> a=vcs.init()
>>> import cdms2 # We need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # use cdms2 to open a data file
>>> s = f('clt') # use the data file to create a slab
>>> a.plot(s,'default','boxfill','quick')
<vcs.displayplot.Dp ...>
>>> a.mode = 0 # Go to manual mode
>>> box=a.getboxfill('quick')
>>> box.color_1=100
>>> box.xticlabels('lon30','lon30')
>>> box.xticlabels('','')
>>> box.datawc(1e20,1e20,1e20,1e20)
>>> box.datawc(-45.0, 45.0, -90.0, 90.0)
>>> a.update() # Update the changes manually
updateorientation(*args)[source]

Takes a string ‘portrait’ or ‘landscape’ and updates a Canvas object’s orientation accordingly.

Parameters

args (str) – String with value ‘landscape’ or ‘portrait’

Attention

This function does not currently work. It will be implemented in the future.

Use landscape() or portrait() instead.

vector(*args, **parms)[source]

Generate a vector plot given the data, vector graphics method, and template. If no vector object is given, then the ‘default’ vector graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('vector') # Show all the existing vector graphics methods
*******************Vector Names List**********************
...
*******************End Vector Names List**********************
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # use cdms2 to open a data file
>>> slab1 = f('u') # use the data file to create a cdms2 slab
>>> slab2 = f('v') # vector needs 2 slabs, so get another
>>> a.vector(slab1, slab2) # plot vector using slab and default vector
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> template=a.gettemplate('hovmuller')
>>> a.vector(slab1, slab2, template) # Plot array using default vector and specified template
<vcs.displayplot.Dp ...>
Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

vector3d(*args, **parms)[source]

Generate a 3d_vector plot given the data, 3d_vector graphics method, and template. If no 3d_vector object is given, then the ‘default’ 3d_vector graphics method is used. Similarly, if no template is given, the ‘default’ template is used.

Note

3d_vectors need 2 data objects (slabs) to plot.

Example
>>> a=vcs.init()
>>> a.show('3d_vector') # Show all 3d_vectors
*******************3d_vector Names List**********************
...
*******************End 3d_vector Names List**********************
>>> dv3=a.get3d_vector() # default 3d_vector
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data file
>>> s = f('u') # use data file to create a cdms2 slab
>>> s2 = f('v') # need two slabs, so get another
>>> # Plot slabs
>>> a.vector3d(dv3, s, s2)  
Sample rate: 6
Sample rate: 6
initCamera: Camera => (...)
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> t = a.gettemplate('polar')
>>> # Plot with 'polar' template
>>> a.vector3d(s, s2, dv3, t)  
Sample rate: 6
Sample rate: 6
initCamera: Camera => (...)
<vcs.displayplot.Dp ...>
xvsy(*args, **parms)[source]
Generate a XvsY plot given the data, XvsY graphics method, and

template. If no XvsY object is given, then the ‘default’ XvsY graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('xvsy') # Show all the existing XvsY graphics methods
*******************Xvsy Names List**********************
...
*******************End Xvsy Names List**********************
>>> xy=a.getxvsy('default_xvsy_') # Create instance of default xvsy
>>> import cdms2 # Need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # use cdms2 to open a data file
>>> slab1 = f('u') # use the data file to create a cdms2 slab
>>> slab2 = f('v') # use the data file to create a cdms2 slab
>>> a.xvsy(slab1,slab2,xy) # Plot array using specified xy and default template
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> template=a.gettemplate('hovmuller')
>>> a.xvsy(slab1,slab2,xy,template) # Plot array using specified xy and template
<vcs.displayplot.Dp ...>
Parameters
  • xaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -1 dim axis. (keyword parameter)

  • yaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -2 dim axis, only if slab has more than 1D. (keyword parameter)

  • zaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -3 dim axis, only if slab has more than 2D. (keyword parameter)

  • taxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -4 dim axis, only if slab has more than 3D. (keyword parameter)

  • waxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -5 dim axis, only if slab has more than 4D. (keyword parameter)

  • xrev (bool) – reverse x axis. (keyword parameter)

  • yrev (bool) – reverse y axis, only if slab has more than 1D. (keyword parameter)

  • xarray (array) – Values to use instead of x axis. (keyword parameter)

  • yarray (array) – Values to use instead of y axis, only if var has more than 1D. (keyword parameter)

  • zarray (array) – Values to use instead of z axis, only if var has more than 2D. (keyword parameter)

  • tarray (array) – Values to use instead of t axis, only if var has more than 3D. (keyword parameter)

  • warray (array) – Values to use instead of w axis, only if var has more than 4D. (keyword parameter)

  • continents (int) – continents type number. (keyword parameter)

  • name (str) – replaces variable name on plot. (keyword parameter)

  • time (A cdtime object) – replaces time name on plot. (keyword parameter)

  • units (str) – replaces units value on plot. (keyword parameter)

  • ymd (str) – replaces year/month/day on plot. (keyword parameter)

  • hms (str) – replaces hh/mm/ss on plot. (keyword parameter)

  • file_comment (str) – replaces file_comment on plot. (keyword parameter)

  • xbounds (array) – Values to use instead of x axis bounds values. (keyword parameter)

  • ybounds (array) – Values to use instead of y axis bounds values (if exist). (keyword parameter)

  • xname (str) – replace xaxis name on plot. (keyword parameter)

  • yname (str) – replace yaxis name on plot (if exists). (keyword parameter)

  • zname (str) – replace zaxis name on plot (if exists). (keyword parameter)

  • tname (str) – replace taxis name on plot (if exists). (keyword parameter)

  • wname (str) – replace waxis name on plot (if exists). (keyword parameter)

  • xunits (str) – replace xaxis units on plot. (keyword parameter)

  • yunits (str) – replace yaxis units on plot (if exists). (keyword parameter)

  • zunits (str) – replace zaxis units on plot (if exists). (keyword parameter)

  • tunits (str) – replace taxis units on plot (if exists). (keyword parameter)

  • wunits (str) – replace waxis units on plot (if exists). (keyword parameter)

  • xweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • yweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • comment1 (str) – replaces comment1 on plot. (keyword parameter)

  • comment2 (str) – replaces comment2 on plot. (keyword parameter)

  • comment3 (str) – replaces comment3 on plot. (keyword parameter)

  • comment4 (str) – replaces comment4 on plot. (keyword parameter)

  • long_name (str) – replaces long_name on plot. (keyword parameter)

  • grid (cdms2.grid.TransientRectGrid) – replaces array grid (if exists). (keyword parameter)

  • bg (bool/int) – plots in background mode. (keyword parameter)

  • ratio () – sets the y/x ratio ,if passed as a string with ‘t’ at the end, will aslo moves the ticks. (keyword parameter)

  • xaxisconvert (str) – (Ex: ‘linear’) converting xaxis linear/log/log10/ln/exp/area_wt

  • yaxisconvert (str) – (Ex: ‘linear’) converting yaxis linear/log/log10/ln/exp/area_wt

  • slab_or_primary_object (array) – Data at least 1D, last dimension(s) will be plotted, or secondary vcs object

Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

xyvsy(*args, **parms)[source]
Generate a Xyvsy plot given the data, Xyvsy graphics method, and

template. If no Xyvsy object is given, then the ‘default’ Xyvsy graphics method is used. Similarly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('xyvsy') # Show all the existing Xyvsy graphics methods
*******************Xyvsy Names List**********************
...
*******************End Xyvsy Names List**********************
>>> xyy=a.getxyvsy('default_xyvsy_') # Create instance of default xyvsy
>>> array=[range(1, 11) for _ in range(1, 11)]
>>> a.xyvsy(array,xyy) # Plot array using specified xyy and default template
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> template=a.gettemplate('hovmuller')
>>> a.xyvsy(array,xyy,template) # Plot array using specified xyy and template
<vcs.displayplot.Dp ...>
Parameters
  • xaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -1 dim axis. (keyword parameter)

  • yaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -2 dim axis, only if slab has more than 1D. (keyword parameter)

  • zaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -3 dim axis, only if slab has more than 2D. (keyword parameter)

  • taxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -4 dim axis, only if slab has more than 3D. (keyword parameter)

  • waxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -5 dim axis, only if slab has more than 4D. (keyword parameter)

  • xrev (bool) – reverse x axis. (keyword parameter)

  • yrev (bool) – reverse y axis, only if slab has more than 1D. (keyword parameter)

  • xarray (array) – Values to use instead of x axis. (keyword parameter)

  • yarray (array) – Values to use instead of y axis, only if var has more than 1D. (keyword parameter)

  • zarray (array) – Values to use instead of z axis, only if var has more than 2D. (keyword parameter)

  • tarray (array) – Values to use instead of t axis, only if var has more than 3D. (keyword parameter)

  • warray (array) – Values to use instead of w axis, only if var has more than 4D. (keyword parameter)

  • continents (int) – continents type number. (keyword parameter)

  • name (str) – replaces variable name on plot. (keyword parameter)

  • time (A cdtime object) – replaces time name on plot. (keyword parameter)

  • units (str) – replaces units value on plot. (keyword parameter)

  • ymd (str) – replaces year/month/day on plot. (keyword parameter)

  • hms (str) – replaces hh/mm/ss on plot. (keyword parameter)

  • file_comment (str) – replaces file_comment on plot. (keyword parameter)

  • xbounds (array) – Values to use instead of x axis bounds values. (keyword parameter)

  • ybounds (array) – Values to use instead of y axis bounds values (if exist). (keyword parameter)

  • xname (str) – replace xaxis name on plot. (keyword parameter)

  • yname (str) – replace yaxis name on plot (if exists). (keyword parameter)

  • zname (str) – replace zaxis name on plot (if exists). (keyword parameter)

  • tname (str) – replace taxis name on plot (if exists). (keyword parameter)

  • wname (str) – replace waxis name on plot (if exists). (keyword parameter)

  • xunits (str) – replace xaxis units on plot. (keyword parameter)

  • yunits (str) – replace yaxis units on plot (if exists). (keyword parameter)

  • zunits (str) – replace zaxis units on plot (if exists). (keyword parameter)

  • tunits (str) – replace taxis units on plot (if exists). (keyword parameter)

  • wunits (str) – replace waxis units on plot (if exists). (keyword parameter)

  • xweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • yweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • comment1 (str) – replaces comment1 on plot. (keyword parameter)

  • comment2 (str) – replaces comment2 on plot. (keyword parameter)

  • comment3 (str) – replaces comment3 on plot. (keyword parameter)

  • comment4 (str) – replaces comment4 on plot. (keyword parameter)

  • long_name (str) – replaces long_name on plot. (keyword parameter)

  • grid (cdms2.grid.TransientRectGrid) – replaces array grid (if exists). (keyword parameter)

  • bg (bool/int) – plots in background mode. (keyword parameter)

  • ratio () – sets the y/x ratio ,if passed as a string with ‘t’ at the end, will aslo moves the ticks. (keyword parameter)

  • xaxisconvert (str) – (Ex: ‘linear’) converting xaxis linear/log/log10/ln/exp/area_wt

  • slab (array) – (Ex: [1, 2]) Data at least 1D, last dimension will be plotted

Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp

yxvsx(*args, **parms)[source]
Generate a Yxvsx plot given the data, Yxvsx graphics method, and

template. If no Yxvsx object is given, then the ‘default’ Yxvsx graphics method is used. Simerly, if no template object is given, then the ‘default’ template is used.

Example
>>> a=vcs.init()
>>> a.show('yxvsx') # Show all the existing Yxvsx graphics methods
*******************Yxvsx Names List**********************
...
*******************End Yxvsx Names List**********************
>>> yxx=a.getyxvsx('default_yxvsx_') # Create instance of default yxvsx
>>> array=[range(1, 11) for _ in range(1, 11)]
>>> a.yxvsx(array,yxx) # Plot array using specified yxx and default template
<vcs.displayplot.Dp ...>
>>> a.clear() # Clear VCS canvas
>>> template=a.gettemplate('hovmuller')
>>> a.yxvsx(array,yxx,template) # Plot array using specified yxx and template
<vcs.displayplot.Dp ...>
Parameters
  • xaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -1 dim axis. (keyword parameter)

  • yaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -2 dim axis, only if slab has more than 1D. (keyword parameter)

  • zaxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -3 dim axis, only if slab has more than 2D. (keyword parameter)

  • taxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -4 dim axis, only if slab has more than 3D. (keyword parameter)

  • waxis (cdms2.axis.TransientAxis) – Axis object to replace the slab -5 dim axis, only if slab has more than 4D. (keyword parameter)

  • xrev (bool) – reverse x axis. (keyword parameter)

  • yrev (bool) – reverse y axis, only if slab has more than 1D. (keyword parameter)

  • xarray (array) – Values to use instead of x axis. (keyword parameter)

  • yarray (array) – Values to use instead of y axis, only if var has more than 1D. (keyword parameter)

  • zarray (array) – Values to use instead of z axis, only if var has more than 2D. (keyword parameter)

  • tarray (array) – Values to use instead of t axis, only if var has more than 3D. (keyword parameter)

  • warray (array) – Values to use instead of w axis, only if var has more than 4D. (keyword parameter)

  • continents (int) – continents type number. (keyword parameter)

  • name (str) – replaces variable name on plot. (keyword parameter)

  • time (A cdtime object) – replaces time name on plot. (keyword parameter)

  • units (str) – replaces units value on plot. (keyword parameter)

  • ymd (str) – replaces year/month/day on plot. (keyword parameter)

  • hms (str) – replaces hh/mm/ss on plot. (keyword parameter)

  • file_comment (str) – replaces file_comment on plot. (keyword parameter)

  • xbounds (array) – Values to use instead of x axis bounds values. (keyword parameter)

  • ybounds (array) – Values to use instead of y axis bounds values (if exist). (keyword parameter)

  • xname (str) – replace xaxis name on plot. (keyword parameter)

  • yname (str) – replace yaxis name on plot (if exists). (keyword parameter)

  • zname (str) – replace zaxis name on plot (if exists). (keyword parameter)

  • tname (str) – replace taxis name on plot (if exists). (keyword parameter)

  • wname (str) – replace waxis name on plot (if exists). (keyword parameter)

  • xunits (str) – replace xaxis units on plot. (keyword parameter)

  • yunits (str) – replace yaxis units on plot (if exists). (keyword parameter)

  • zunits (str) – replace zaxis units on plot (if exists). (keyword parameter)

  • tunits (str) – replace taxis units on plot (if exists). (keyword parameter)

  • wunits (str) – replace waxis units on plot (if exists). (keyword parameter)

  • xweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • yweights (array) – replace xaxis weights used for computing mean. (keyword parameter)

  • comment1 (str) – replaces comment1 on plot. (keyword parameter)

  • comment2 (str) – replaces comment2 on plot. (keyword parameter)

  • comment3 (str) – replaces comment3 on plot. (keyword parameter)

  • comment4 (str) – replaces comment4 on plot. (keyword parameter)

  • long_name (str) – replaces long_name on plot. (keyword parameter)

  • grid (cdms2.grid.TransientRectGrid) – replaces array grid (if exists). (keyword parameter)

  • bg (bool/int) – plots in background mode. (keyword parameter)

  • ratio () – sets the y/x ratio ,if passed as a string with ‘t’ at the end, will aslo moves the ticks. (keyword parameter)

  • xaxisconvert (str) – (Ex: ‘linear’) converting xaxis linear/log/log10/ln/exp/area_wt

  • slab (array) – (Ex: [1, 2]) Data at least 1D, last dimension will be plotted

Returns

A VCS displayplot object.

Return type

vcs.displayplot.Dp