! image_to_kmz.jnl
\cancel mode verify
!
! ACM 7/1/2009 -- created
! ATW 7/2/2009 -- minor modifications
!
! 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)

DEFINE SYMBOL kml_write LIST/QUIET/nohead/norowhead/file="($kmlname)"/format=(a)

! 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.

($kml_write)/clobber {"<?xml version='1.0' encoding='UTF-8'?>"}
($kml_write)/append  {"<kml xmlns='http://earth.google.com/kml/2.1'>"}

!<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.

($kml_write)/append {"    <Folder>"}


!<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.

($kml_write)/append {"      <GroundOverlay>"}

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

($kml_write)/append {"         <name>($dispname)</name>"}

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

($kml_write)/append {"         <LookAt>"}
($kml_write)/append {"               <longitude>180</longitude>"}
($kml_write)/append {"               <latitude>20</latitude>"}
($kml_write)/append {"               <range>3035000.36838438907</range>"}
($kml_write)/append {"               <tilt>0</tilt>"}
($kml_write)/append {"               <heading>0</heading>"}
($kml_write)/append {"         </LookAt>"}

!<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.
($kml_write)/append {"         <visibility>1</visibility>"}

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

($kml_write)/append {"         <Icon>"}
($kml_write)/append {"            <href>($gifFile)</href>"}
($kml_write)/append {"         </Icon>"}


!<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.

($kml_write)/append {"         <LatLonBox>"}
($kml_write)/append {"             <north>($ppl$ymax)</north>"}
($kml_write)/append {"             <south>($ppl$ymin)</south>"}
($kml_write)/append {"             <east>($ppl$xmin)</east>"}
($kml_write)/append {"             <west>($ppl$xmax)</west>"}
($kml_write)/append {"             <rotation>0</rotation>"}
($kml_write)/append {"         </LatLonBox>"}


! Close the remaining tags

($kml_write)/append {"      </GroundOverlay>"}
($kml_write)/append {"    </Folder>"}
($kml_write)/append {"</kml>"}

cancel symbol kml_write

set mode/last verify
