classdef kml < handle
%KML(name) Create a KML toolbox object, that allows you to plot from MATLAB to Google Earth
% 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.
%
% With it, you can create:
% - line plots, scatter plots
% - 2D and 3D contours
% - 2D and 3D polygons
% - quiver plots
% - write text in a given point
% - place 3D models
% - overlay images
% - transfer more complex figures as images
% - folders, subfolders,... to aggregate similar plots
%
% For some usage examples, check the code at .\test\RunTests.m
%
% If you enjoy it, just drop me an email at kml@rafael.aero saying for what you're using it :).
%
% Copyright 2012 Rafael Fernandes de Oliveira (rafael@rafael.aero)
% $Revision: 2.3 $ $Date: 2012/09/05 08:00:00 $
properties %(Access = private, Transient)
xml
doc
parent = []
filename = ''
name = ''
unit = 'deg'
zip = true
includeFiles;
end
properties (Access = private)
target = 'earth'
end
methods
function this = kml(name,parent)
if nargin <1
name = 'Unnamed KML';
end
this.name = name;
if nargin <2
parent = [];
else
if ~isa(parent,'kml')
error('Invalid parent, pass only a kml object or a kml folder')
end
end
this.parent = parent;
if isempty(parent)
this.xml = com.mathworks.xml.XMLUtils.createDocument('kml');
kmlNode = this.xml.getDocumentElement;
kmlNode.setAttribute('xmlns','http://www.opengis.net/kml/2.2');
kmlNode.setAttribute('xmlns:gx','http://www.google.com/kml/ext/2.2');
kmlNode.setAttribute('xmlns:kml','http://www.opengis.net/kml/2.2');
kmlNode.setAttribute('xmlns:atom','http://www.w3.org/2005/Atom');
this.doc = this.xml.createElement('Document');
this.doc.appendChild(this.textNode('name',name));
kmlNode.appendChild(this.doc);
else
this.doc = parent.xml.createElement('Folder');
this.xml = parent.xml;
this.doc.appendChild(this.textNode('name',name));
this.doc.appendChild(this.textNode('id', name));
parent.doc.appendChild(this.doc);
end
end
function clear(this)
if isempty(this.parent)
%not a folder, just create a new kml class and reuse it's xml nodes
a = kml(this.name);
this.doc = a.doc;
this.xml = a.xml;
this.includeFiles = '';
a.delete;
else
this.parent.doc.removeChild(this.doc);
a = kml(this.name,this.parent);
this.doc = a.doc;
this.xml = a.xml;
a.delete;
end
end
function addIncludeFile(this,varargin)
K = this;
while ~isempty(K.parent)
K = K.parent;
end
newFiles = varargin;
for i = 1:numel(newFiles)
K.includeFiles{end+1} = newFiles{i};
end
end
function save(this,filename, compact)
if ~isempty(this.parent)
warning('KML:incompletefile','You are saving only a folder of the KML file, not the full KML, this will not load on any viewer');
end
if nargin < 2
if isempty(this.filename)
if strcmpi(this.name,'Unnamed KML')
[tmpvar,filename] = fileparts(tempname(cd));
filename = [filename '.kml'];
warning('KML:tempfile','Please delete file %s later, if not required...',filename);
else
filename = this.name;
end
else
filename = this.filename;
end
end
if nargin < 3
compact = this.zip;
else
this.zip = compact;
end
[p,fn,ext] = fileparts(filename);
filename = fullfile(p,[fn '.kml']);
xmlwrite(filename,this.xml);
if this.zip
[p,fn,ext] = fileparts(filename);
kmzFilename = fullfile(p,[fn '.kmz']);
zip(kmzFilename,vertcat({filename},this.includeFiles(:)).');
delete(filename);
movefile([kmzFilename '.zip'],kmzFilename,'f');
this.filename = kmzFilename;
else
this.filename = filename;
end
end
function viewKML(this)
tmpfile = [tempname '.kml'];
xmlwrite(tmpfile ,this.xml);
edit(tmpfile);
delete(tmpfile);
end
function run(this)
this.save;
switch true
case ispc
system(['start "kmltoolbox" "' this.filename '"']);
case ismac
system(['open' ' "' this.filename '"']);
otherwise
disp('The KML file has been saved, open it in Google Earth');
end
end
function useRadians(this)
this.unit = 'rad';
end
function useDegrees(this)
this.unit = 'deg';
end
function setTarget(this,target)
target = lower(target);
assert(ismember(target,{'earth','moon','sky','mars'}),'Target must be one of the following: ''earth'' ''moon'' ''mars'' or ''sky''')
this.target = target;
kmlNode = this.xml.getDocumentElement;
if ~strcmpi(this.target,'earth')
kmlNode.setAttribute('hint',['target=' this.target]);
end
end
function varargout = checkUnit(this,varargin)
varargout = varargin;
parent = this;
while ~isempty(parent.parent)
parent = parent.parent;
end
if strcmpi(parent.unit,'deg')
%do nothing
elseif strcmpi(parent.unit,'rad')
for i = 1:numel(varargin)
varargout{i} = varargin{i}.* (180/pi);
end
else
error('invalid angular unit %s', parent.unit);
end
end
function disp(this)
display(this);
end
function display(this)
if getpref('kmltoolbox','ShowDisclaimer',true)
disp(sprintf('\n'));
disp(' _ ____ __ _ _____ _ _ ')
disp(' | |/ / \/ | | |_ _|__ ___| | |__ _____ __')
disp(' | '' <| |\/| | |__ | |/ _ \/ _ \ | ''_ \/ _ \ \ /')
disp(' |_|\_\_| |_|____| |_|\___/\___/_|_.__/\___/_\_\')
disp(sprintf('\n'));
disp('Copyright 2012 Rafael Fernandes de Oliveira (rafael@rafael.aero)')
disp(sprintf('\n'));
disp('If you enjoy it, just drop me an email at kml@rafael.aero saying for what you''re using it :-)')
disp(sprintf('\n'));
disp('To install the toolbox, and suppress this message, run kml.install')
end
end
end
methods %(Access = private)
function node = textNode(this,Name,Text)
node = this.xml.createElement(Name);
node.appendChild(this.xml.createTextNode(Text));
end
end
methods (Static)
iconURL = parseIconURL(iconURL)
im = captureScreen(view)
function colorHex = color2kmlHex(color)
if numel(color) ==3
color(4) = 1;
end
color = min(max(floor(color*255),0),255);
[r,g,b,a] = deal(color(1),color(2),color(3),color(4));
[rhex, ghex, bhex, ahex ]= deal(dec2hex(r),dec2hex(g),dec2hex(b),dec2hex(a));
if length(rhex)==1,rhex=['0' rhex];end
if length(ghex)==1,ghex=['0' ghex];end
if length(bhex)==1,bhex=['0' bhex];end
if length(ahex)==1,ahex=['0' ahex];end
colorHex = [ahex bhex ghex rhex];
end
function ID = getTempID(rootID)
[tmp,tmpID] = fileparts(tempname);
ID = [rootID tmpID];
end
function dist = ll2dist(lon1, lat1,lon2, lat2)
%Input in radians - Calculate distance using Haversine formula
R = 6378137;
dLat = (lat2-lat1);
dLon = (lon2-lon1);
a = sqr(sin(dLat/2)) + cos(lat1) .* cos(lat2) .* sqr(sin(dLon/2));
c = 2 * atan(sqrt(a)./sqrt(1-a));
dist = R * c;
end
function install()
clc
nl = sprintf('\n');
disp(nl);
disp(' _ ____ __ _ _____ _ _ ')
disp(' | |/ / \/ | | |_ _|__ ___| | |__ _____ __')
disp(' | '' <| |\/| | |__ | |/ _ \/ _ \ | ''_ \/ _ \ \ /')
disp(' |_|\_\_| |_|____| |_|\___/\___/_|_.__/\___/_\_\')
disp(nl);
disp('This will add the KML toolbox to your MATLAB path, at the current location');
disp('If you prefer to have it located somewhere else, first copy the whole folder');
disp('to the place you want, and then run kml.install from there!');
disp(nl);
p = fileparts(fileparts(mfilename('fullpath')));
disp(sprintf('Toolbox Path: %s',p));
disp(nl);
s = input('Continue [Y]/N? ','s');
if strcmpi(s,'n')
disp('Instalation aborted!')
return
end
disp(nl);
disp('Adding toolbox folder to the MATLAB path...')
disp(nl);
disp('(In some systems, this might require administrative rights, sorry for that)')
disp(nl);
addpath(p);
addpath(fullfile(p,'html'));
r = savepath;
if r == 1
disp('Error saving your path. Please add the toolbox folder manually to your MATLAB path')
end
disp('Installing the toolbox help...')
warning('off','MATLAB:doc:DocNotInstalled')
builddocsearchdb(fullfile(p,'html'))
warning('on','MATLAB:doc:DocNotInstalled')
setpref('kmltoolbox','ShowDisclaimer',false);
clc
disp(nl);
disp(' _ ____ __ _ _____ _ _ ')
disp(' | |/ / \/ | | |_ _|__ ___| | |__ _____ __')
disp(' | '' <| |\/| | |__ | |/ _ \/ _ \ | ''_ \/ _ \ \ /')
disp(' |_|\_\_| |_|____| |_|\___/\___/_|_.__/\___/_\_\')
disp(nl);
disp(nl);
disp(' Toolbox installed successfully!')
disp(nl);
disp('To take a look in the toolbox contents, run: >> kmldoc');
disp('To get help for the toolbox functions, run: >> kmldoc kml.FunctionName');
disp(nl);
end
end
end