ISL Images and Movies

7.1.5 ISL Images and Movies

The image and movie tag are the ones used to create images and movies. Both of these tags can contain subtags that allow you to manipulate the image or images.

<image> Generate and manipulate images

The image tag allows you to capture an image from a main display or from the GUI of a display control.

The file attribute defines the image file. For image formats that support it you can also specify a quality attribute that can range from close to 0.0(worst) to 1.0 (best and default).

The view attribute allows you to specify a name of a view it use. This can also be a regular expression pattern to use to match on multiple views. If there are multiple views in existence and there is no view attribute specified or if there multiple views resulting from a view name attribute you should use the viewindex and viewname in your filenames, etc., The viewindex property is the number of the view, e.g., the first view we capture has viewindex of 0, the second viewindex = 1, etc.

The display attribute allows you to specify a display control to use to capture. For its use see here. The what attribute allows you to specify what part of the display control gui should be captured. For now the IDV only supports what="chart" to capture the time series chart of the station model and data probe displays.

<movie> Create a Quicktime movie, animated GIF or Google Earth KMZ file

The movie tag allows you to capture a time animation as a Quicktime movie, Google Earth KMZ file or as an animated gif.

The view attribute is the same as in the image tag.

If the file ends with .mov then a Quicktime movie is created. If the file ends with .gif then an animated gif is created. If the file ends with .kmz then a Google Earth KMZ file is created each being time stamped. Note: The file attribute can be a comma separated list of files, e.g.:

<movie file="test.mov,test.kmz,test.gif"/>

This allows you to capture multiple types of movie products in one call.

The imagetemplate is a template filename that can contain text and three different macros, e.g.:

imagetemplate="image_%time%"    Include the animation time formatted in the default format
imagetemplate="image_%count%"   Include which image
imagetemplate="image_%count%_%time:any date format%"  Include animation time in any date format. e.g.:
imagetemplate="image_%count%_%time:yyyyMMddHHmm%"

The generic date format can contain a specification that is used by the Java SimpleDateFormat and is described in Basic Tags.

KML Attributes

The movie tag also supports a set of KML specific attributes that allow you to configure the generated KML file.

      <movie
         file="test.kmz"
         kml_desc="<a href="${wwwroot}/${bundle}">Run in the IDV</a> (Needs Java Webstart)"
         kml_name="${label}"
         kml_visibility="0"
         kml_open="0">

kml_desc is the description for the KML Folder that holds the images. It can contain html
kml_name is the folder name.
kml_visibility specifies whether the images are shown initially or not.
kml_open specifies whether the Folder is open or not.

Using your own images

You can also use any number of contained fileset tags to define a custom list of images that are used instead of the default images derived from an animation capture.

<movie file="test.mov">
   <fileset file="image1.png"/>
   <fileset file="image2.png"/>
   <fileset file="image3.png"/>
</movie>

<panel> Create a gridded layout of a set of images. This is just like the movie tag and support all of the above attributes

The panel tag acts just like the movie tag except that it merges all of the images into one image in a panelized or gridded fashion. It is column oriented so you specify the number of columns:

<panel file="test.gif" width="400" columns="2" space="10"/>

<publish> Publish a file to RAMADDA

<html> Create an image from rendered html

The html tag allows you to specify html that is rendered into an image. It acts just like the image tag in that in can contain image manipulation commands. The html is either from a file (specified by the fromfile attribute) or contained in a CDATA block:

<html file="foo.png">
   <![CDATA[
hello there
<hr>
This is my test
]]>
   <matte bottom="50" background="red"/>
</html>

Images Manipulation

There are a set of tags that can be contained by both the image and movie tags that support processing of the image. Most of these tags work on the initial image and act as a filter pipeline. For example, the ISL:

<image file="test.png">
    <clip north="40" south="30" east="-80" west="-90"/>
    <matte bottom="150"/>
</image>

Will generate an image from the main display. It will then clip the image at the given lat/lon bounding box and then add a matte with spacing of 150 pixels at the bottom of the image. It will then write out the image to the file test.png.

You can modify this behavior in a variety of ways. For example, the ISL:

<image file="test.png">
    <clip north="40" south="30" east="-80" west="-90" copy="true" file="clippedimage.gif"/>
    <matte bottom="150"/>
</image>

will clip the original image but not alter it (the copy="true") and then will write out the clipped image to the given file. The original image will be passed to the matte tag which will matte it.

The image manipulation tags can be nested. e.g. the ISL:

<image file="test.png">
    <clip north="40" south="30" east="-80" west="-90" copy="true" file="clippedimage.gif">
        <matte bottom="150"/>
        <write file="somefile.jpg"/>
        <transparent color="black"/>
    </clip>
    <matte bottom="150"/>
</image>

Will clip a copy of the image, matte the copy, write out the matted image as somefile.jpg, set the color black to be transparent and then write it out as clippedimage.gif. The original image is then matted and written out as test.png.

<clip> Clip an image

The clip tag allows you to clip the image. The clipping can either be defined in lat/lon coordinates, with x/y image coordinates or from the projection used from a display. The image coordinates can be specified as percentages. If no arguments are given then we clip the image at the box.

Clip in image space:
<clip top="10" bottom="0" left="10%" right="0"/>

Clip in lat/lon space:
<clip north="40" south="30" east="-80" west="-90"/>
Note: The view should be in a lat/lon projection and an overhead view for clipping in lat/lon
space to be accurate.


Clip at the 3D box:
<clip/>

Clip at the 3D box with 10 pixel padding
<clip space="10"/>

Clip at the 3D box with horizontal spacing of 10 pixels and vertical spacing of 30
        <clip hspace="10" vspace="30"/>

Clip with left/right/bottom/right spacing
        <clip space_left="5" space_right="40" space_bottom="10" space_top="-10"/>

If there is a display attribute defined then we get the lat/lon bounds of its data to clip with. Use the display control Properties dialog to set the id that you reference in the ISL.

Clip using a display id:
<clip display="displayid"/>

<matte> Matte an image

The matte tag allows you to add a space around any of the sides of an image. e.g:

<matte top="100" bottom="20"/>

You can also simply specify a space, hspace (horizontal space), or vspace (vertical space) attributes:

<matte space="10"/>

<matte hspace="20"/>

<matte vspace="20"/>

You can also specify a background color. The color can be a named color or a comma separated list of red/green/blue values:

<matte top="100"  background="black"/>
or:
<matte top="100"  background="red,green,blue values"/>

<overlay> Annotate an image with text or a logo

The overlay tag allows you to add an icon or text as an image overlay. You can either specify and image or text. The place and anchor tags specify the location of the overlay. They take the form: "rectpoint,offsetx,offsety" Where rectpoint is a point on a rectangle:

   UL    UM    UR
   ML    MM    MR
   LL    LM    LR
   Where U=upper,M=middle,L=lower
   R=right,L=left

The offsetx and offsety are optional. The idea is you define a point on the base image, e.g., the upper left corner ("ul"). Then you define an anchor point on the overlay that will be placed at the place point. So for example, if you wanted the upper left corner of the image overlay to be drawn 10 pixels right and 20 pixels below the upper left corner of the base image then you would do:

   place="UL,10,20" anchor="UL"

If you wanted some text overlay to be placed so that its bottom center was in the middle of the image, 30 pixels from the bottom of the image you do:

   place="LM,0,-30" anchor="LM"

If you wanted some overlay to be placed so that its upper right was placed at the center of the image you do:

   place="M" anchor="UR"

<image file="test.gif">
   ...
  <show message="Here is the image"/>
  ...
</image>

<latlonlabels> Add lat/lon labels to an image

The latlonlabels tag allows you to add lat/lon labels to an image. Note: For this to be correct your image needs to be in a geographic projection in an overhead view.

<?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"/>
  <image file="${islpath}/test.png">
<!-- 
Note: none of these attributes are required and the "xxx" attributes are just commented out

lonvalues/latvalues - Comma separated list of lonvalues and latvalues.

lonlabels/latlabels - An optional list of  labels to use instead of the values

format - A decimal format for formatting the lat/lons if you don't
specify the lonlabels/latlabels.

labelbackground -  if defined, will be the background  color of the labels.

top/bottom/left/right - This is the matte-ing of the image.
If a value is undefined or 0 then the label is shown on the inside of the map image.
If non-zero then the label is shown on the outside of the map image.

background  - background color of the matted border

showleft/showright/showtop/showbottom - controls what labels are shown

drawlonlines/drawlatlines - draw lines across the map

linewidth/linecolor - line attributes

dashes - comma separated list of line segment lengths. format is:
opaque length1, transparent length1,opaque length2, transparent length2,...
defaults to solid line

lineoffsetleft/lineoffsetright/... - offsets when drawing lat/lon lines
defaults to 0

-->

    <latlonlabels 
       lonvalues="-160,-140,-120,-100,-80,-60,-40,-20,0,20,40,60,80,100,120,140,160" 
       xxxlonlabels="a,b,c,d" 
       latvalues="-80,-60,-40,-20,0,20,40,60,80" 
       xxxlatlabels="a,b,c,d" 

       format="##0"
       xxxlabelbackground="white"

       background="gray"
       top="30"
       bottom="0"
       left="30"
       right="0"

       showleft="true"
       showright="true"
       showtop="true"
       showbottom="true"

       drawlonlines="true" 
       drawlatlines="true"
       linewidth="1"
       linecolor="green"
       dashes="2,10"

       lineoffsetleft="0"
       lineoffsetright="0"
       lineoffsettop="0"
       lineoffsetbottom="0"

       />

  </image>
</isl>
latlonlabels.isl

<displaylist> Render the display list

The displaylist tag renders the display list (normally shown at the bottom of the view) directly into the image. The text rendering is a bit higher quality because we are using direct Java drawing code and not the 3D rendering. Also, you can matte an image and then render the list of displays in the matted area.

You will want to turn off the visibility of the display list for the view (under View->Show->Display List menu) when you save the bundle.

<show> Show the current image in a dialog

You can use the show tag inside an image or movie tag to show the current image in a dialog. This allows you to see what is going on and debug your isl image generation.

<resize> Resize an image

The resize tag allows you to resize an image. You specify either a width or a height:

<resize width="200"/>

<resize height="150"/>

The width or height can also be a percentage:

<resize width="50%"/>

<resize height="10%"/>

<thumbnail> Generate a thumbnail of an image

The thumbnail tag is just like the resize tag except that it will also write out the image. e.g:

<thumbnail width="50%" file="thumbnail.png"/>

<write> Write out an image

The write tag allows you to write out an intermediate image file at any time.

    <write file="somefile.png"/>

<colorbar> Add a color bar to an image

The colorbar tag allows you to add a color bar from the color tables in the display controls. Currently, it does not do a perfect job when there are more than one color tables present.

The orientation attribute specifies where the tick marks are drawn, e.g., to the left, right, top or bottom of the color bar. This also implicitly specifies the horizontal (top, bottom) or vertical (right, left) orientation of the color bar. Note, placing a vertical color bar is a bit tricky.

You can specify how ticks are drawn. You can give a number of tickmarks, a value interval or a specific list of values.

The location of the color bar is defined using the anchor and place points as described for the overlay tag.

Here is an example that loads a bundle, creates an image, mattes the image and then shows the color bar of a display with id "planview".

<?xml version="1.0" encoding="ISO-8859-1"?>
<isl debug="true" loop="1" offscreen="true" sleep="60.0minutes">
  <bundle clear="true" file="${islpath}/colorbar.xidv" wait="true"/>
  <image file="${islpath}/colorbar.png">
     <matte space="100" background="gray"/>
     <colorbar display="planview" orientation="top" tickmarks="3" width="400" showlines="true"  anchor="LM" place="UM,0,100" showunit="true"/>
     <colorbar display="planview" orientation="bottom" tickmarks="3" width="400" showlines="true"  anchor="UM" place="LM,0,-100" showunit="true"/>
     <colorbar display="planview" orientation="top" tickmarks="3" width="400" showlines="true"  anchor="LM" place="LM" showunit="true"/>
     <colorbar display="planview" orientation="left" tickmarks="3" width="20" height="400" showlines="true"  anchor="MR" place="ML,100,0" showunit="true"/>
     <colorbar display="planview" orientation="left" tickmarks="3" width="20" height="400" showlines="true"  anchor="MR" place="MR" showunit="true"/>
  </image>
</isl>
colorbar.isl

That makes:

<kmlcolorbar> Write a colorbar into the kmz file

The kmlcolorbar tag acts just like the colorbar tag but is intended to generate a separate color bar image (written to the file specified by the file attribute) and include it into a KMZ file.

All of the kml. attributes are simply passed into the generated KML file and are used to place the image into Google Earth. These attributes are the attributes and tags in the KML. For example, the attribute kml.overlayXY.x ends up being the x attribute of the overlayXY tag in the KML. See here http://code.google.com/apis/kml/documentation/kmlreference.html#screenoverlay for more info on the KML.

Here is an example:

<?xml version="1.0" encoding="ISO-8859-1"?>
<isl debug="true" loop="1" offscreen="true" sleep="60.0minutes">
  <bundle clear="true" file="${islpath}/testtwoview.xidv" wait="true"/>
  <image file="${islpath}/test.kmz">
  <kmlcolorbar  width="400" height="20"
        showlines="true" tickmarks="4"  fontsize="12" background="white" color="black"
        file="${islpath}/testcolorbar.png" space="20" suffix=" %unit%"
        kml.name="Color bar"
        kml.overlayXY.x="0" kml.overlayXY.y="1" kml.overlayXY.xunits="fraction" kml.overlayXY.yunits="fraction"
        kml.screenXY.x="10" kml.screenXY.y="1" kml.screenXY.xunits="pixels" kml.screenXY.yunits="fraction"/>
  </image>
  
</isl>
kmlcolorbar.isl

<transparent> Set transparency on an image

The transparent tag allows you to set a particular color in an image to be transparent.

<transparent color="black"/>
or:
<transparent color="red,green,blue"/>

<backgroundtransparent> Set transparency on an image. Use the background color of the view.

The backgroundtransparent tag allows you to use the background color of the view as the transparent color in the image

<backgroundtransparent/>

<split> Split an image into sub-images

The split tag splits up an image by a given number of rows and columns. The file attribute should contain properties for each image: ${row}, ${column} and ${count}.

Unidata's Integrated Data Viewer > Miscellaneous > IDV Scripting