Scripting
McIDAS-V can be scripted to create and manipulate images and movies. The scripting
is accomplished using Jython. Jython is an implemenation of the Python language
in Java and follows Python syntax.
McIDAS-V scripting can be done from the Jython
shell, or a Jython script can be invoked as a command line argument.
In Unix, from the McIDAS-V-System directory:
runMcV -script /home/user/example.py
In Windows, from the McIDAS-V System directory (if running under a Windows machine,
it is necessary to use "\\" instead of "\" in scripts when specifying directory
paths to avoid Windows interpreting it as an escape sequence.):
runMcV.bat -script C:\\home\\user\\example.py
When invoked as a command line argument, the user interface will not be shown.
However, McIDAS-V still needs to be run with an active window system (e.g.,
X, MS Windows) for it to run. If running under a Linux/Unix machine and you
don't have an X server running you need to run McIDAS-V under the X virtual
frame buffer, xvfb.
McIDAS-V supports a number of functions and methods to load and display data,
manipulate the display, and to save images. Download the example script
to see how to use each one (example.py).
The following are supported in McIDAS-V.
Create an Object:
Modify the Display Object:
Modify the Layer Object:
Save the Display:
Create an Object:
buildWindow - Creates
a window and returns an array of panels (single panel currently supported)
Usage: panel=buildWindow(keywords)
Keywords:
height= height of the window
width= width of the window
panelTypes= type of display to create
MAP (default)
GLOBE
openBundle - Creates
a new window and displays contents of a bundle
Usage: openBundle(bundle file, keywords)
bundle file - file name of bundle (required)
Keywords:
height= height of display; default= height of the
display window when the bundle was saved
width= width of display; default= width of the display
window when the bundle was saved
dataDictionary= a dictionary where the keys are datasource
names, and the values are either a string or list of strings representing
the full path name/names of the data that will be used in place of the data
in the bundle
getADDEImage - Requests
data from an ADDE Image server - returns both data and metadata objects
Usage: myMetaData,myData= getADDEImage(keywords)
Keywords:
server= ADDE server
dataset= ADDE dataset group name
descriptor= ADDE dataset descriptor
day= day range ('begin date','end date')
time= ('begin time','end time')
coordinateSystem= coordinate system to use for retrieving
data
AREA AREA file coordinates - zero
based
LATLON latitude and longitude coordinates
IMAGE image coordinates
- one based
location=(x,y)
x AREA
line, latitude, or IMAGE line
y AREA
element, longitude, or IMAGE element
place = CENTER places specified location (x,y) at
center of panel
ULEFT places specified location (x,y) at upper-left
coordinate of panel
band= McIDAS band number; must be specified if requesting
data from multi-banded image; default=band in image
unit= calibration unit to request; default = 'BRIT'
position= time relative (negative values) or absolute
(positive values) position in the dataset; default=0 (most recent image)
size= number of lines and elements to request; default=(480,640)
mag= magnification of data (line,element), negative
number used for sampling data; default=(1,1)
accounting= ('user', 'project number') user and project
number required by servers using McIDAS accounting; default = ('idv','0')
createLayer - Creates
a new data layer in a panel
Usage: myDataLayer = panel[0].createLayer(display
type, myData)
display type - display type for layer; valid options
shown in Field Selector (e.g. 'Image Display', 'Image Sequence Display')
myData - data object to display (from getADDEImage)
Modify the Display Object:
annotate - Writes text
to a panel
Usage: panel[0].annotate(text,keywords)
text - annotation string
Keywords:
lat=, lon= Start text string at specified latitude and longitude (must be used together)
line=, element= Start text string at specified panel
line and element (must be used together)
font= name of font; default is system dependent
size= size of font; default 12
color= 'color name'; default='red'
-or-
[R,G,B] fractional scaling factor for each red, green
and blue value (0 to 1)
setCenter -
Centers the display on a specified latitude/longitude and sets a scaling factor
Usage: panel[0].setCenter(latitude,longitude,keywords)
latitude - centers the display at the specified latitude (no default, required parameter)
longitude - centers the display at the specified longitude (no default, required parameter)
Keywords:
scale= scale factor for map; default=current scale factor
Scale factors between 0 and 1 zoom out centered on the specified
latitude/longitude and scale factors greater than 1 zoom in.
setProjection - Sets
the projection of a panel
Usage: panel[0].setProjection(projection)
projection - string specifying the projection;
e.g., 'US>Southeastern U.S.'
-or-
the name of the layer returned by createLayer, which
uses the default projection of that data
setWireframe - Turns
wire frame box on or off
Usage: panel[0].setWireframe(visible)
visible - True displays wire frame box, False turns
off wire frame box
Modify the Layer Object:
setColorScale - Displays
color scale on a panel and specifies its attributes
Usage: myDataLayer.setColorScale(keywords)
Keywords:
visible= True displays color scale (default)
placement= location of color scale
'Top' (default)
'Bottom'
'Left'
'Right'
font= name of font; default=font defined in user
preferences
style= font style; default=font defined in user
preferences
BOLD bolded font
ITALIC italicized font
NONE
size= size of font; default=size of font defined
in user preferences
color= 'color name'; default=color defined in user
preferences
-or-
[R,G,B] fractional scaling factor for each red, green
and blue value (0 to 1)
setEnhancement - Applies
a color table and defines data range of data in a layer
Usage: myDataLayer.setEnhancement(color table,keywords)
color table - color table name e.g., 'Longwave Infrared
Deep Convection'
Keywords:
range=(min,max) enhancement range; default= (min,max)
of data
setLayerLabel - Toggles
a layer label on/off and defines its attributes
Usage: myDataLayer.setLayerLabel(label,keywords)
label - layer label string
Keywords:
visible= True displays layer label
font= name of font; default=font defined in user
preferences
style= font style; default=font defined in user
preferences
BOLD bolded font
ITALIC italicized font
NONE
size= size of font; default=size of font defined
in user preferences
color= 'color name'; default=color defined in user
preferences
-or-
[R,G,B] fractional scaling factor for each red, green
and blue value (0 to 1)
setLayerVisible
- Toggles layer visibility on/off
Usage: myDataLayer.setLayerVisible(visible)
visible - True displays layer
False turns off layer
Save the Display:
captureImage - Writes
panel display to a file
Usage: panel[0].captureImage(file, keywords)
file - name of file, file format determine by file
extension; valid options: .jpg, .gif, .png, .pdf, .svg, .kml, .kmz
Keywords:
height= height of image (default - see Remarks)
width= width of image (default - see Remarks)
quality= quality of jpg file (0.0 to 1.0); default=1.0;
not used with other formats
Remarks:
If captureImage is used to save a panel that was created
with openBundle, the sizes default to size of the display window when the bundle
was saved. If data was loaded using createLayer, the sizes default to those
defined in buildWindow.
writeMovie - Writes
an image sequence to a movie file (ISL function)
Usage: writeMovie(file,keywords)
file - name of file, file format determine by file
extension; valid options: .gif, .mov
Keywords:
resize width= height= frame size of the movie
For users looking for more functionality from McIDAS-V scripting, additional
functions can be found in the Java docs for
visAD,
netCDF,
IDV,
and McIDAS-V.
Please send any questions or requests for functionality to the
McIDAS-V
Support Forum on scripting.