! image_to_kml.jnl
\cancel mode verify
!
! ACM 7/1/2009
!
! Write a kml file containing a Ferret image for use in Google Earth.
! The tags that are written to the file are take from the documentation
! at http://code.google.com/apis/kml/documentation/kmlreference.html
! and comments in this script are take from that document.
!
! The image is made as a gif image with any missing data set to be
! transparent, so that the Google Image map will show through it.
!
say START FERRET WITH ferret -gif SO THAT THE IMAGE CAN BE MADE WITH TRANSPARENCY
!
! Usage:
!
! > ferret -gif
!
!                        arg 1   arg 2   arg 3        arg 4    arg 5       arg 6
!Usage:  GO image_to_kml gifFile kmlFile plot_command variable [xcoordVar] [YcoordVar]
! 
!    gifFile		gif file to be saved
!    kmlFile		kml file to write
!    plot_command	2D plot command including palette, levels etc
!    variable		variable to plot, must be 2D in longitude/latitude
!    xcoordVar		For curvilinear grids, the longitude coordinate variable
!    xcoordVar		For curvilinear grids, the latitude coordinate variable
!
!
!Examples:
! > ferret -gif
!
! yes? USE etopo20
! yes? GO image_to_kml rose.gif rose.kml SHADE/Y=-60:60/pal=dark_land_sea/lev=c rose
!
!    ! or for a variable with curvilinear coordinates geolon,geolat:
!
! yes? use my_curvilinear_data.nc
! yes? GO image_to_kml curv.gif curv.kml FILL/MOD/HLIM=-180:180 var[t=1-jan-2005] geolon geolat

query/ignore $1%Argument 1 is a gif file name%
query/ignore $2%Argument 2 is a kml file name%
query/ignore $3%Argument 3 is the plot comand%
query/ignore $4%Argument 4 is the variable in XY"%

DEFINE SYMBOL pcommand = $3
DEFINE SYMBOL var = $4

IF $5"0|*>1" THEN 
   DEFINE SYMBOL var ($var),$5"0"
ENDIF
IF $6"0|*>1" THEN 
   DEFINE SYMBOL var ($var),$6"0"
ENDIF

DEFINE SYMBOl gifFile = $1
IF `STRINDEX("($gifFile)","gif") EQ 0` THEN 
   SAY Argument 1 is a gif file name
   EXIT/SCRIPT
ENDIF

DEFINE SYMBOL kmlname = $2
IF `STRINDEX("($kmlname)","kml") EQ 0` THEN 
   SAY Argument 2 is a kml file name
   EXIT/SCRIPT
ENDIF

DEFINE SYMBOL dispname = FerretPlot

DEFINE VIEW/AXES/XLIM=0:1/YLIM=0:1 WMSview
SET VIEW WMSview

($pcommand) ($var)
FRAME/TRANS/FORMAT=gif/FILE=($gifFile)

! Header lines
!<kml>
!    The root element of a KML file. This element is required. 
!    It follows the xml declaration at the beginning of the file.

let kml_line = "<?xml version='1.0' encoding='UTF-8'?>"
LIST/QUIET/nohead/norowhead/clobber/file=($kmlname)/format=(a) kml_line

let kml_line = "<kml xmlns='http://earth.google.com/kml/2.1'>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

!<Folder>
!    A Folder is used to arrange other Features hierarchically 
!   (Folders, Placemarks, NetworkLinks, or Overlays). A Feature is visible 
!    only if it and all its ancestors are visible.

let kml_line = "    <Folder>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line


!<GroundOverlay>
!    This element draws an image overlay draped onto the terrain. The
!    <href> child of <Icon> specifies the image to be used as the overlay. 
!    This file can be either on a local file system or on a web server.

let kml_line = "      <GroundOverlay>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

!<name>
!    User-defined text displayed in the 3D viewer as the label for 
!    the object (for example, for a Placemark, Folder, or NetworkLink).

let kml_line = "         <name>($dispname)</name>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

!<LookAt>
!    Defines a virtual camera that is associated with any element 
!    derived from Feature.

let kml_line = "         <LookAt>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

let kml_line = "               <longitude>180</longitude>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "               <latitude>20</latitude>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "               <range>3035000.36838438907</range>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "               <tilt>0</tilt>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "               <heading>0</heading>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "         </LookAt>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

!<visibility>
!    Boolean value. Specifies whether the feature is drawn in the 3D viewer when it 
!    is initially loaded. In order for a feature to be visible, the <visibility> 
!    tag of all its ancestors must also be set to 1. In the Google Earth LIST/QUIET View, 
!    each Feature has a checkbox that allows the user to control visibility of the Feature.
let kml_line = "         <visibility>1</visibility>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

!<Icon>
!    Defines an image associated with an Icon style or overlay. 
!    (For this script this is a simple gif image file.)

let kml_line = "         <Icon>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "            <href>($gifFile)</href>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "         </Icon>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line


!<LatLonBox>
!    Specifies where the top, bottom, right, and left sides of a bounding box for the ground overlay are aligned.
!
!        * <north> Specifies the latitude of the north edge of the bounding box, in decimal degrees from 0 to ±90.
!        * <south> Specifies the latitude of the south edge of the bounding box, in decimal degrees from 0 to ±90.
!        * <east> Specifies the longitude of the east edge of the bounding box, in decimal degrees from 0 to ±180. (For overlays that overlap the meridian of 180° longitude, values can extend beyond that range.)
!        * <west> Specifies the longitude of the west edge of the bounding box, in decimal degrees from 0 to ±180. (For overlays that overlap the meridian of 180° longitude, values can extend beyond that range.)
!        * <rotation> Specifies a rotation of the overlay about its center, in degrees. Values can be ±180. The default is 0 (north). Rotations are specified in a counterclockwise direction.

let kml_line = "         <LatLonBox>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

define symbol outsym = <north>($ppl$ymax)</north>
let kml_line = {"             ($outsym)"}
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

define symbol outsym = <south>($ppl$ymin)</south>
let kml_line = {"             ($outsym)"}
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

define symbol outsym = <east>($ppl$xmin)</east>
let kml_line = {"             ($outsym)"}
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

define symbol outsym = <west>($ppl$xmax)</west>
let kml_line = {"             ($outsym)"}
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

let kml_line = "             <rotation>0</rotation>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "         </LatLonBox>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line


! Close the remaining tags

let kml_line = "      </GroundOverlay>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "    </Folder>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line
let kml_line = "</kml>"
LIST/QUIET/nohead/norowhead/append/file=($kmlname)/format=(a) kml_line

! --- end of image_to_kml.jnl ---