KML Toolbox v2.6

Create KML/KMZ files and view them in Google Earth. Supports 3D models, contours, overlays, and more

Description

This class-based toolbox allows you to create many different plots in Google Earth, by automatically creating the required xml-based KML files without user interaction. Also allows to save as KMZ packages, including any model & images necessary for the plot.

With it, you can create:
- line plots, scatter plots
- 2D and 3D contours
- 2D filled contours
- 2D and 3D polygons
- 2D and 3D quiver plots
- write text in a given point
- place 3D models
- 3D surfaces
- overlay images
- transfer more complex figures as images
- folders, subfolders,... to aggregate similar plots
- animate 3D models into a pre-defined trajectory
- camera position
- animated tours (still undocumented, but there is now an example in the test folder - more info, contact me by email).

To install the toolbox into your MATLAB path, go to the toolbox directory and run:
>> kml.install

Now with documentation of each function and the available parameters. To view the help, run in MATLAB:
>> kmldoc
or
>> kmldoc kml.plot %or any other of the available plots

If you enjoy it, just drop me an email at [e-mail] saying for what you're using it :).

Inspired by the original Google Earth Toolbox, but implemented using MATLAB classes and XML, which makes it much easier to use. It was tested with 2011a onwards, but it should work in older releases too... (Let me know if not!)

Acknowledgements

Google Earth Toolbox inspired this file.

• Required Products: MATLAB
• MATLAB release: MATLAB 7.12 (R2011a)

[Richard Gueler]

I found a bug with the overlay function. If I try to add an overlay image with a path in the filename, it embeds the state path in the kml file, thus when I load the kmz file into Google Earth, it goes looking for the file at the stated path. It does not use the file embedded with the kmz file.

For example, if I do the following,

k.overlay(west,east,south,north,'file','C:\temp\myImage.png');

Google Earth will grab the image "C:\temp\myImage.png", not the one embedded with the kmz file. I suggest you remove the path from the filename that is used in the kml file.

Other than that, it is a great toolbox.

[Martin Lechner]

Hi Rafael,

in the file
function target = plot(this,long,lat,varargin)

I found an issue in the chech of the lat and long input value (line 14 and 15).
The function handle includes directly the check for the input value &&~isempty(lat). This must be &&~isempty(a).

This lines should be:
p.addRequired('lat', @(a)isnumeric(a) && isvector(a) &&~isempty(a));
p.addRequired('long',@(a)isnumeric(a) && isvector(a) &&~isempty(a) && numel(a)==nlat);

[Rafael Oliveira]

@Ryan: thanks for reporting the error, you can fix it by changing that line to:

if iscell(arg.iconColor) && nc==nlat

I'll submit a fixed version of the toolbox.

@Alfredo: I've changed the save function, now it should be possible to save to other folders as well - thanks for the tip. And to avoid those lines, just make sure you end every plot command with a ;

[Ryan]

Hi Rafael,

I really like this tool box, I have been using it quite a bit.

I wanted to report a possible error:

When using k.scatter3(lon,lat,z, ...
'iconColor','FFFF0000','iconScale',.2);

I get an error when plotting exactly 8 points
Cell contents reference from a non-cell array object.

Error in kml/scatter3 (line 131)
iconstyle.appendChild(this.textNode('color',arg.iconColor{i}));

-It seems to happen here in the scatter3 function because nc==nlat returns true, and it should probably be false.
if nc==nlat
iconstyle.appendChild(this.textNode('color',arg.iconColor{i}));
else
iconstyle.appendChild(this.textNode('color',arg.iconColor));
end

Thanks again for the toolbox

[Ryan]

 

[Alfredo]

It would be cool that the k.save function supported the path in the filename. i.e.:

k.save('path\filename.kml')

Now it ignores the path and saves the kml file in the current folder.
Thank you

Also, how can I avoid the display of the following lines in the Command Window? Thanks

ans =

type: 'Placemark'
id: [1x47 char]

[Alfredo]

It would be cool that the k.save function supported the path in the filename. i.e.:

k.save('path\filename.kml')

Now it ignores the path and saves the kml file in the current folder.
Thank you

[Nick Mortimer]

Just a quick comment, I'm doing some stuff that requires accurate lat and longs have gone through and changed

num2str(north) to num2str(north,8) to avoid loosing position accuracy

[Jaroslaw Tuszynski]

Works great

[Robert Daly]

Hi Rafael,
Thanks for making this great tool. I had a minor issue with the klm.transfer function not lining up properly. I discovered that this was because my plotting script used "axis equal". This resulted in the axes not filling the whole figure window during the image capture so the image limits were not quite right. perhaps you could add "axis normal" in the code somewhere so that it will always behave as expected.

[Rafael Oliveira]

Sorry Tomas, but the toolbox needs a MATLAB version that supports classes, which are definitely not available at R2007b...

[Tomas]

Matlab version 2007b:
>>kml.install
??? No appropriate method or public field install for class kml.
When I try:
>>kmldoc %KML toolbox appear but its not functional.

[Rafael Oliveira]

and for those interested in the animation feature, here is a little example of using it:

k = kml('testAnimation');
k.useRadians;
N = numel(longitude);
yaw = yaw - pi; %This is to correct the mis-orientation in the A320 model, you can ignore this for other models - or fix the model file
modelA320 = k.model(longitude(1),latitude(1),altitude(1),yaw(1),gamma(1),roll(1),'model','A320.dae','scale',10);
anim = k.newAnimation('Flight');

for i = 2:N
dT = time(i) - time(i-1);
anim.updateLocation(modelA320,dT,longitude(i),latitude(i),altitude(i));
anim.updateOrientation(modelA320,dT,yaw(i)-pi,gamma(i),roll(i));

anim.flyToLookAt(dT, longitude(i), latitude(i),1e4)
end

anim.flyToLookAt(10, mean(longitude),mean(latitude),1e5);

k.run;

[Rafael Oliveira]

Hi John,
I've answered you by email, but in any case, the fix is to replace the num2str(id) with num2str(i). Anyway, I've submitted a fixed version of the toolbox, that also includes some other bug fixes.

[John Fuller]

 

[John Fuller]

Rafael,
I get the following error when I run the quiver function example snippet:

k = kml('my kml file');

% Create a sample quiver plot in the kml file
[x,y] = meshgrid(-5:.2:5,-2:.15:2);
z = x .* exp(-x.^2 - y.^2) + y.*sin(x);
[px,py] = gradient(z,.2,.15);
k.quiver(5*x,10*y,8*px,8*py)

% Save the kml and open it in Google Earth
k.save;
??? Undefined function or variable 'id'.

Error in ==> kml.quiver at 61
target(i) = f.plot(long2,lat2, 'altitude',arg.altitude,...

Any thoughts?

[Seb Biass]

Thanks a lot for the contourf function! Just fyi, the [~, ixMA] at line 137 gives errors on old (i.e. 2009) versions. Another question... are you implementing a way to specify the contour values rather than the number of contours?
Cheers!

[AHMET ANIL DINDAR]

This is a perfect toolbox.

++Ahmet

[Rina]

 

[Rafael Oliveira]

Hi Seb Biass, I've finally added contourf to the toolbox :)
If you find any bugs on it, let me know!
@Stephan - I've almost finished screen overlay support, I'll update it as soon as I've time to finish and test it.

[Stephan]

Would it be possible to include screen overlays?

[Seb Biass]

That is really nice, thank you! Any chance for a contourf type function?

[Rafael Oliveira]

Hi Zeneida,
You can do it using the option 'numberOfLevels', as in:

k = kml;
[x,y,z] = peaks;
k.contour(x,y,z, 'numberOfLevels', 20);
k.run;

[Zeneida]

Hello,
There is a way do more contours, I need that more contour lines in the map, but I don't know is it can be. In the contour.m from matlab I can specify the number of lines, but here?????
Thank you

[Rafael Oliveira]

Thanks for the tip... I've included it in an updated version, together with a change removing the ~ from the function outputs. Now it should work with some older MATLAB versions too!

[Balam Willemsen]

Very nice and useful! I made one very small edit to kml.m to get it to work on the Mac platform. Not sure if Linux has a common tool like start or open that is independent of distro.

function run(this)
this.save;
if (ispc)
system(['start "kmltoolbox" "' this.filename '"']);
elseif (ismac)
system(['open' ' "' this.filename '"']);
elseif (isunix)
disp('The KML file has been saved, open it in Google Earth');
end

end

[Michele Williams]

This is a great program ... it has provided a great way to visualize my measurement results spatially.

[scott lee davis]

hey this looks great! Why not combine the two versions into the best matlab version? I am building at multilanguage version of the googleearth toolbox and would welcome motivated matlab development and extension.

http://code.google.com/p/googleearthtoolbox/source/browse/#git%2Fmatlab

[Rafael Oliveira]

Hi Travis. I've used the same name, but they're all encapsulated inside the kml class... So, to call them, you need to create an instance of the kml class, for example:

mykml = kml('Sample plot');

And then use this object "mykml" to plot, as in:

mykml.plot(1:10, sin(1:10));

or

mykml.scatter(rand(100,1),rand(100,1));

[Travis Knepp]

I am wondering why you built functions with the same name as MatLab built-in functions (e.g. plot.m, plot3.m, text.m)? This seems pretty counter-productive. Can you correct me on this?

[Julien]

The object oriented version of the google earth toolbox. Wonderful! Thank you so much for sharing...