Previous: File ISL Tags Next: ISL Images and Movies Table of contents Images Frames Unidata's Integrated Data Viewer > Miscellaneous > IDV Scripting

7.1.3 ISL Data and Displays

<bundle> Load a bundle
<bundle
    file="bundle file or url"
    width="view window width"
    height="view window height"
    times="List of times to use"
    bbox="north,west,south,east"
    clear="default is true. remove all existing displays and data"
    wait="default is true. wait until all displays have been rendered."
    window="default is false. if set to true and in the isl offscreen mode, the idv window will be created."
    bbox="override the geoSelection bounding box."
    timedriverstart="changing the animation widget time driver start time."
    timedriverend="changing the animation widget time driver end time." >

The bundle tag lets you load in a new bundle and takes the form:

<bundle file="some_bundle_file.xidv"/>
By default it will remove all currently loaded data and displays. If you want to not clear out the data and displays then add a clear="false" attribute:
<bundle file="some_bundle_file.xidv" clear="false"/>

The bbox attribute is a string of the form "north,west,south,east" and will relocate any gridded data to use these bounds.

The wait attribute, if true (the default), will essentially do a pause, waiting until all displays have been rendered.

The window attribute, if true and in offscreen mode, will generate idv window object, that is needed when saving to a zidv bundle.

The times attribute allows you to override the set of time indices that are used in the data sources in the bundle. Note: this overrides the times for all data sources in the bundle.

The value is a comma separated list of time specifiers where the specifier can be a single time, a time range or a time range with a step. The time indices are 0 based, e.g., the first time index is 0. The time range is of the form "firsttime:lasttime". To specify a step do: "firsttime:lasttime:step"

For example, we have:

   times="0"                    -- Just use the first time
   times="2"                    -- Just use the third time
   times="0,1,2"                -- Just use the first 3 times
   times="0:10"                 -- 0 through 10
   times="0:10:2"               -- 0,2,4,6,8,10
   times="0:10:2, 20:30"        -- 0,2,4,6,8,10 20-30
   times="1,2,3,5:11:2,20,30"   -- 1,2 3, 5,7,9,11, 20, 30
The ensembles attribute allows you to override the set of ensemble indices that are used in the data sources in the bundle. Note: this overrides the ensembles for all grid data sources in the bundle. The syntax is the same as for times.

For example, we have:

   ensembles="0"                -- Just use the first ensemble members
   ensembles="0,1,2"            -- Just use the first 3 ensemble members
   ensembles="0:10:2"           -- ensemble members 0,2,4,6,8,10
   etc...
The bbox attribute allows you to override the geoselection bounding box. Note: this overrides all grid data sources in the bundle and creates display in the new geoselection area.

For example, we have:

<bundle file="some_bundle_file.xidv" bbox="50,-110,30,-100"/>
The timedriverstart and timedriverend attributes allow you to override the animation widget time driver start time and end time. If there is no time driver setting in the animation widget, these two attributes will be ignored.

For example, we have:

<bundle file="some_bundle_file.xidv" timedriverstart="yyyy-MM-dd HH:mm:ss Z" timedriverend="yyyy-MM-dd HH:mm:ss Z"/>

<setfiles> Override the files or urls used in a bundle
<setfiles
    datasource="identifier of the data source"
    file="new file or url path" >

The bundle tag can contain any number of "setfiles" tags. Each of these setfiles tags has a datasource attribute which is used to find the data source in the bundle by name. There is also a file attribute which defines a file to use for that data source.

e.g.:

<isl debug="true" offscreen="false">
    <bundle file="test.xidv">
         <setfiles datasource=".*" file="/upc/share/testdata/grid/netcdf/nuwg/ruc.nc"/>
     </bundle>
     <image file="test.png"/>
</isl>
The bundle above only has one data source. The:
datasource=".*" 
identifies the data source by name. In this case it is a regular expression that matches anything. If you had multiple data sources you can change their name before you save the bundle (right click on the data source in the field selector and got to the Properties dialog.) You can then use these names to match. e.g.:
<isl debug="true" offscreen="false">
    <bundle file="test.xidv">
        <setfiles datasource="datasource1" file="file for first data source"/>
        <setfiles datasource="datasource2" file="file for 2nd data source"/>
    </bundle>
    <image file="test.png"/>
</isl>
If you have a data source with multiple files (e.g., radar) you can use an embedded fileset tag:
<setfiles datasource="datasource1">
    <fileset file="some file"/>
    <fileset file="some other file"/>
     ...
</setfiles>

<datasource> Create a data source
<datasource
    url="url or file name to load"
    type="data source type"
    times="List of times to use"
    ensembles="List of ensembles to use" >

The datasource tag lets you create a new data source and takes the form. The url attribute is required and specifies the file or url to load. The type attribute is optional and defines the data source type from the datasources.xml file in the source release. For a text listing see Datasources.html. For now you can only specify a data source that takes a single url (or filename). This will change in the future. The times and ensembles attributes work the same as in the bundle tag above.

<isl>
  <datasource url="dods://motherlode.ucar.edu/cgi-bin/dods/DODS-3.2.1/nph-dods/dods/casestudies/idvtest/grids/small_ruc_grid.nc">
<!-- Set the name on the data source  -->
    <property
       name="name"
       value="the name"/>
  </datasource>
</isl>
datasource.isl
One or more spatial subset attributes can be specified for data sources that support them:


    stridex = the X skip factor (stride)
    stridey = the Y skip factor
    stridez = the Z skip factor
    bbox    = the geographic bounding box (N,W,S,E)

For example:
  <isl>
  <datasource
       url="dods://motherlode.ucar.edu:8080/thredds/dodsC/casestudies/idvtest/grids/small_ruc_grid.nc" stridex="2" stridey="3" stridez="2" bbox="40,-113,20,-98"/>
  </isl>
would select every other X gridpoint, every 3rd Y gridpoint, every other level and data between 40N and 20N and 113W and 98W.
<display> Create a display
<display
    type="display type"
    param="parameter name" >

The display tag lets you create a display and can exist on its own:

<display type="somedisplaytype" param="some_parameter"/>
or as a child tag of the datasource tag:
<isl>

<!-- Create   a datasource. Note: you can also have a template attribute
     that points to a bundle xidv file that was saved from a data source:
     bundle="${islpath}/datasource.xidv"
-->

  <datasource 
     url="dods://motherlode.ucar.edu:8080/thredds/dodsC/casestudies/idvtest/grids/small_ruc_grid.nc"
     id="datasource1">
<!-- Set the name on the data source  -->
    <property
       name="name"
       value="Example data source"/>
<!-- Create a display of RH. Here we load in the display from a template.  -->
<!--
    <display
       param="RH" template="${islpath}/template.xidv">
      <property
         name="id"
         value="display1"/>
      <property
         name="displayCategory"
         value="Category 1"/>
      <property
         name="legendLabelTemplate"
         value="%datasourcename% - %shortname%"/>
    </display>
-->


<!-- Create a display of T. Here we create the display from the type -->
    <display
	type="planviewcontour"
      param="T">
      <property
         name="displayCategory"
         value="Category 1"/>
<!--
        The contour info can be set with: interval;base;min;max
              <property name="contourInfoParams" value="10;40;-30;100"/>
         Or it can have names in it:
-->
      <property name="contourInfoParams" value="interval=10;base=40;min=-30;max=100;dashed=true;labels=false"/>

<!--
you can also specify irregular levels with levels=, e.g.:
      <property name="contourInfoParams" value="levels=10,20,30;dashed=true;labels=false"/>
-->

      <property
         name="legendLabelTemplate"
         value="%datasourcename% - %shortname%"/>

<!-- This sets the level to be 500 hectopascals -->
<!-- Note: this can also be of the form #<index>, eg. #4 will select the 5th level (this is zero based) -->

      <property
         name="dataSelectionLevel"
         value="500[hectopascals]"/>


    </display>
  </datasource>


<!-- Set the projection to the data projection  of the display we created above  -->
<!--
  <center
     display="display1"
     useprojection="true"/>
-->

</isl>
display.isl
The type attribute is one of the display control types defined in the controls.xml file from the source release and is required. For a text listing see controls.txt.

The param attribute is not required. If specified it is the name of a parameter in either the containing datasource tag or in one of the currently loaded data sources. The display tag will evolve in time to provide a richer set of facilities for setting values on the display.

The property tags define various properties to apply to the display. See here for a listing.

The spatial subset attributes described in the datasource tag above can be used with each display to override the default.


<loadcatalog> Load a remote catalog URL
<loadcatalog
    url="url to the catalog" >


<removedisplays> Remove all displays
<removedisplays
    display="display id to remove" >

This removes all current displays. If there is the display attribute set then it removes that display. (See below).

<removedisplays/>

<removeall> Remove all data and displays
Remove all current data and displays.
<removeall/>

<reload> Reload all loaded data
The reload tag tells all of the loaded data sources to reload, resulting in updated displays.
<reload/>

<center> Center a display at a lat/lon, or from a display control
<center
    lat="latitude"
    lon="longitude"
    north="latitude"
    south="latitude"
    east="longitude"
    west="longitude"
    display="display id to center at"
    useprojection="Use the projection from the display" >

The center tag comes in a number of forms, depending on the attributes:

<isl>
    <bundle file="test.xidv"/>
    <pause/>

    <echo message="Set the projection to be the projection of the first display"/>
    <center/>
    <pause seconds="10"/>

    <echo message="Center at a point"/>
    <center lat="15" lon="-65"/>
    <pause seconds="10"/>

    <echo message="Set the projection to be the lat/lon box"/>
    <center north="40.0" south="30" east="-90" west="-100"/>
    <pause seconds="10"/>

    <echo message="Set the projection from the specified display"/>
    <center display="display1" useprojection="true"/>
    <pause seconds="10"/>

    <echo message="Center at the center of the given displays projection"/>
    <center display="display1" useprojection="false"/>
    <pause seconds="10"/>

</isl>
center.isl
Using the display attribute specifies a display control to use. This can take two forms. First, you can specify a simple text pattern that we try to match on the displays id. The id can be set from the display controls property dialog.
display="some name"
The second method is to specify a class name or partial class name:
display="class:ucar.unidata.idv.TrackControl"
or:
display="TrackControl"

<projection> Changing bundle or data projection
<projection
    name="The name of existing projection" >

<isl>
    <bundle file="test.xidv"/>
    <pause/>

    <echo message="Changing the projection defined in the bundle to be North America"/>
    <projection name="North America"/>
    <pause seconds="10"/>

</isl>
projection.isl
In this example, the projection of the bundle is changed to North America.
<viewpoint> Change the viewpoint or aspect ratio of a view
<viewpoint
    rotx="Rotation X"
    roty="Rotation Y"
    rotz="Rotation Z"
    transx="Translation X"
    transy="Translation Y"
    transz="Translation Z"
    scale="Scale"
    aspectx="Aspect ratio x"
    aspecty="Aspect ratio y"
    aspectz="Aspect ratio z"
    tilt="Tilt degrees"
    azimuth="Asimuth degrees" >

The viewpoint tag comes in a number of forms, depending on the attributes:

<?xml version="1.0" encoding="ISO-8859-1"?>
<isl debug="true" loop="1" offscreen="false" sleep="60.0minutes">
  <bundle clear="true" file="${islpath}/test.xidv" wait="true"/>
  <pause seconds="5"/>

<!-- Specify a rotation, translation and scale. These values are shown in the Aspect Ratio tab of the View Manager properties dialog  -->
  <viewpoint  rotx="75" roty="62" rotz="-3.3" scale="0.399" transx="0.0" transy="0.0" transz="0.0"/>
  <pause seconds="5"/>

<!-- You can also set the aspect ratio  -->
  <viewpoint  aspectx="2" aspecty="5" aspectz="10"/>
  <pause seconds="5"/>

<!-- You can also specify a tilt and azimuth. This is the same as you can do interactively in the viewpoint dialog -->
  <viewpoint  tilt="45" azimuth="180"/>
  <pause seconds="5"/>

</isl>
viewpoint.isl
The rot/trans/scale values can be viewed in the Aspect Ratio tab of the View Manager properties dialog.
<export> Export data to netCDF or CSV
<export
    file="The file where the data will be exported. The correct file suffix will be added automatically"
    what="The choices are "csv" and/or "netcdf""
    display="The display class or ID" >

<?xml version="1.0" encoding="ISO-8859-1"?>
<isl debug="true" loop="1" offscreen="true" sleep="60.0minutes">
  <bundle clear="true" file="${islpath}/test.xidv" wait="true"/>
  <export file="/tmp/test" what="csv, netcdf" display="class:ucar.unidata.idv.control.ObsListControl"/>
</isl>
export.isl
Currently, the only display attribute available for the export tag is
display="class:ucar.unidata.idv.control.ObsListControl"
or an ID of a display control that refers to an instance of the ObsListControl (e.g. a Point Data List display for METAR data).
<export> Export xidv to zidv
<export
    file="The file where the zidv will be exported. The correct file suffix zidv is required."
    what="zidv" >

<?xml version="1.0" encoding="ISO-8859-1"?>
<isl debug="true" loop="1" offscreen="true" sleep="60.0minutes">
  <bundle clear="true" file="${islpath}/test.xidv" wait="true"/>
  <displayproperties display="class:ucar.unidata.idv.control.ContourPlanViewControl">
      <property name="DisplayAreaSubset"  value="true"/>
  </displayproperties>
  <export file="/tmp/test/test.zidv" what="zidv" />
</isl>
exportZidv.isl
In the case the user only want to save the display area data in the zidv, the SetDisplayAreaSubset api can be called inside the displayproperties tag to spatially subset the data in the data source property level, with the condition of only one view window exists in the current IDV, before exporting to the zidv. The spatial subset property change of data source only needs to be done once and will be passed to all data sources.

 


Previous: File ISL Tags Next: ISL Images and Movies Table of contents Images Frames Unidata's Integrated Data Viewer > Miscellaneous > IDV Scripting