Contents
| Table of Contents |
|---|
Getting up-and-running
For plotting Google Earth in Matlab we made the GooglePlot toolbox as part of the Matlab OpenEarthTools. To get a copy of this free and open source toolbox, (i) register for the svn repository, (ii) install the TorToiseSVN svn client for windows, and use that to get a copy of the complete toolbox, and (iii) activate openearthtools in your Matlab session by adding it to your path with oetsettings. Running this will display a message screen with a clickable link to GooglePlot. Otherwise type help googleplot. This will display a list of all available plot types for Google Earth. We attempted to create a version for each regular Matlab plot command by prepadding kml, e.g. kmlsurf will plot a surface just like Matlabs own surf. We actually created more plot types than matlab itself offfers, i.e. KMlquiver for curved arrows and KMLcy;linder for a 3D cylinder.
...
The following code snippet will generate a KMlsurf object.
| Code Block |
|---|
[lon,lat,z]=peaks
surf(peaks)
KMLsurf(lat,lon,z)
|
...
Each GooglePlot function, and in fact most openearthtools Matlab functions, adhere to a specific convention that allows users to pass extra parameters using keyword-value pairs. This approach is similar to the way Matlab allows users to modify properties of plots, figures and axis. For instance, to change the color and width of a line plot, Matlab specifies this syntax for a thick grey line (RGB value of .5).
| Code Block |
|---|
plot(x,y),'color',[.5 .5 .5],'linewidth',2) |
You can also ask for a plot handle when you call it, and then ask for all keywords that you can modify with {get}}, get all default values with set, and also modify a selection with set.
| Code Block |
|---|
h = plot(x,y)
get(h)
set(h)
set(h,'color',[.5 .5 .5],'linewidth',2)
|
OpenEarthTools adopted this approach, facilitated by the important core function setproperty (we test this function very thoroughly due its central function, in fact other scripting languages provide this function in their core, as kwargs in python). For tool users, remember out convention that you can call a GooglePlot without arguments to get a list of all properties. This will generate a list with the default values. You can also edit the function to see the struct with all properties. For developers to use this keyword-value functionality, call oetnewfun to start a new function using a template.
| Code Block |
|---|
KMLsurf
ans =
kmlName: ''
snippet: ''
description: ''
fileName: ''
...
lineWidth: 1
lineColor: [0 0 0]
...
zScaleFun: @(z)(z+20).*5
...
colorbar: 1
colorMap: @(m)jet(m)
colorSteps: 16
cLim: []
...
timeIn: []
timeOut: []
|
...
If you use GooglePlot often, the pop-up for a filename is annoying and blocks automation. Keyword 'FileName' allows you to pass the filename to prevent a pop-up. You noticed that KMLsurf was a bit slow. For testing this extra options, it would be nice to have a faster option available. KMLmesh produces also a 4D grid, but without color. The extension you specify determines whether you get an kml or a kmz file. The kml file format is a specific xml file, following the open source OGC KML standard. This is an ascii file, which can become rather big. You can simply zip the kml file, and then rename it to *.kmz. A kmz file is simply an ordinary zip file with a kml inside, plus images that are associated with the plot, in this case the colorbar image. We recommend always to select kmz as extension, to prevent separate colorbar images from appearing in your folder.
| Code Block |
|---|
KMLmesh(lat,lon,z,'fileName','KMLmesh.kmz')
|
You will notice that the black line in KMLmesh.kmz are ill-visible on the blue ocean, use keyword lineColor to set the lines to white, using the rgb triplet 1 1 1 to produce KMLmesh_white.kmz.
| Code Block |
|---|
KMLmesh(lat,lon,z,'fileName','KMLmesh_white.kmz','lineColor',[1 1 1])
|
...
The KMLsurf and KMLmesh plots look like regular pcolor plots, they are flat. The reason for this is that the vertical span is very small compared to the radius of the earth. With keyword zScaleFun you can specify a function for the vertical exaggeration. We chose tyo make this a function, so you cna also apply a logarithmic transformation to view the deep ocean floor (4000m) and shelf depths (orde 40 m) in the same plot. The default transformation is oen that is appropriate for the foreshore and dune bathymetry (MSL -20 to +30) in the Netherlands, where we first lift the surface out of the water (adding deepest depth of 20m), and then apply a vertical exaggeration factor of 5: zScaleFun: @(z)(z+20).*5. For this example we will have to do something more extreme: we lift the surface somewhat out of the water, and then multiply by 1e5, which is roughly 10 times the thickness of the atmosphere.
| Code Block |
|---|
KMLmesh(lat,lon,z,'fileName','KMLmesh_white_zscaled.kmz','lineColor',[1 1 1],'zScaleFun',@(z)(z+1).*5e4)
|
...
When we have judged the appropriate scaling in KMLmesh_white_zscaled.kmz by fast testing with KMLmesh, we can make a slower KMLsurf plot: KMLsurf_zscaled.kmz.
| Code Block |
|---|
KMLsurf(lat,lon,z,'fileName','KMLsurf_zscaled.kmz','zScaleFun',@(z)(z+1).*5e4)
|
...
When you call KMLsurf without argument, many keywords deal with colors. You can tweak these to tailor the plot for your purpores. For bathymetries, we created the symmetric colormapbathymetry colormap, that has blues in its first half, and yellow just above 0 (sandy beaches) and greens for the remainder. This one is optimized for colorlimits where MSL is exactly in the middle, here we choose -5 ..5, and apply 10 colorSteps so each color exactly represents a range of 1 (the color ticks coincide with the color changes). To keep such long calls readable, we end each line with ... and padd the next line with spaces to the commas line up as a column.
| Code Block |
|---|
KMLsurf(lat,lon,z,'fileName','KMLsurf_zscaled_clim.kmz',...
'zScaleFun',@(z)(z+1).*5e4,...
'cLim',[-5 5],...
'colorMap',@(m) colormapbathymetry(m),...
'colorSteps',10,...
'CBcolorTitle','altitude scaled [m]')
|
...
For movies you have to activate the inherent time functionality of Google Earth. By defautl objects are static, unless the proeprties TimeIn and TimeOut are set. Mkare sure the time window between TimeIn and TimeOut is sufficiently long to see the object, and make sure that the subsequent object's TimeIn is not after the previous' objects TimeOut, to prevent flickering. A small overlap can be prescribed. Google Earth always plots a later object on top of a previous object, so only in gaps previous objects are visible. In fact, you can set the Google time slides to have a time span that contains multiple time frames (drag left part of slider to left, away from right part of slider). For faster movies, make the Google Earth time slides as narrow as possible. For cycling movies, such as seasons or tides, make sure the first and last image have a smooth transition (not a duplicate of same state), and enable the movie loop option to produce KMLsurf_movie.kmz.
| Code Block |
|---|
%% make a kml file for each movie frame
T = 12;
for it=1:T
kmlnames{it} = ['KMLsurf_movie_',num2str(it,'%0.2d'),'.kml'];
[~,colorbarname]=KMLsurf(lat,lon,z*cos(2*pi*it/T),'fileName',kmlnames{it},...
'zScaleFun',@(z)(z+1).*5e4,...
'CBcLim',[-5 5],...
'colorMap',@(m) colormapbathymetry(m),...
'colorSteps',10,...
'colorbar',it==T,...
'timeIn',it,...
'timeOut',it+1,...
'CBcolorTitle','altitude scaled [m]');
end
%% merge time frames into one kml
KMLmerge_files('fileName','KMLsurf_movie.kml','sourceFiles',kmlnames)
%% merge kml with colorbar into kmz, and cleanupo intermediate files
KML2kmz('KMLsurf_movie.kml',colorbarname)
deletefile('KMLsurf_movie.kml',colorbarname,kmlnames)
|
...