1; -----------------------------------------------------------------------------
2;
3;  Copyright (C) 1997-2013  Krzysztof M. Gorski, Eric Hivon, Anthony J. Banday
4;
5;
6;
7;
8;
9;  This file is part of HEALPix.
10;
11;  HEALPix is free software; you can redistribute it and/or modify
12;  it under the terms of the GNU General Public License as published by
13;  the Free Software Foundation; either version 2 of the License, or
14;  (at your option) any later version.
15;
16;  HEALPix is distributed in the hope that it will be useful,
17;  but WITHOUT ANY WARRANTY; without even the implied warranty of
18;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19;  GNU General Public License for more details.
20;
21;  You should have received a copy of the GNU General Public License
22;  along with HEALPix; if not, write to the Free Software
23;  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
24;
25;  For more information about HEALPix see http://healpix.sourceforge.net
26;
27; -----------------------------------------------------------------------------
28pro write_kml_file, img_file, kml_file, box=box, rotation=rotation, title=title, subtitle=subtitle
29
30; this default box works for an image with RA increasing towards the left
31if undefined(box) then box ={north:90.d0,south:-90.d0,east:180.d0,west:-180.d0}
32
33if undefined(rotation) then rotation = 0.
34
35;;;help,img_file,kml_file
36openw,lun,kml_file,/get_lun
37
38printf,lun,'<?xml version="1.0" encoding="UTF-8"?>'
39printf,lun,'<kml xmlns="http://earth.google.com/kml/2.1" hint="target=sky">'
40printf,lun,'<!--'
41printf,lun,'      To open this KML Folder under Google Earth: do'
42printf,lun,'           File > Open and select this file.
43printf,lun,'     '+systime()
44printf,lun,' -->'
45printf,lun,'  <Folder>'
46printf,lun,'    <name>Healpix sky data</name>'
47printf,lun,'    <description>Healpix data in Google format</description>'
48printf,lun,'    <GroundOverlay>'
49;;printf,lun,'      <altitude>0</altitude>'
50if defined(title)    then printf,lun,'      <name>'+title+'</name>'
51if defined(subtitle) then printf,lun,'      <description>'+subtitle+'</description>'
52printf,lun,'      <Icon>'
53printf,lun,'        <href>'+img_file+'</href>'
54printf,lun,'      </Icon>'
55printf,lun,'      <LatLonBox>'
56printf,lun,'      <!-- Swapping North and South (or East and West) numbers will flip the image accordingly-->
57printf,lun,'        <north>'+strtrim(box.north,2)+'</north>'
58printf,lun,'        <south>'+strtrim(box.south,2)+'</south>'
59printf,lun,'        <east>' +strtrim(box.east,2) +'</east>'
60printf,lun,'        <west>' +strtrim(box.west,2) +'</west>'
61printf,lun,'        <rotation>'+strtrim(rotation,2)+'</rotation>'
62printf,lun,'      </LatLonBox>'
63printf,lun,'    </GroundOverlay>'
64printf,lun,'  </Folder>'
65printf,lun,'</kml>'
66free_lun,lun
67
68print,'KML file created in '+kml_file
69
70return
71end
72;--------------------------------------------------
73pro cartgoogle, file_in, select_in, $
74                gif = gif, $
75                kml = kml, $
76                png = png, $
77                _extra = other_kwds, $
78                reso_arcmin = reso_arcmin, $
79                subtitle = subtitle, $
80                titleplot = titleplot
81;+
82; NAME:
83;
84;
85;
86; PURPOSE:
87;    Turns a Healpix data set into a PNG or GIF file, and a KML folder file, usuable by Google Sky
88;
89;
90; CATEGORY:
91;
92;
93;
94; CALLING SEQUENCE:
95;   Cartgoogle, data [, select, GIF=, KML=, PNG=, RESO_ARCMIN=, SUBTITLE=,
96;   TITLEPLOT=,
97;   + all CARTVIEW's keywords (COLT=, FACTOR=, GRATICULE=, IGRATICULE=, HBOUND=,
98;   HIST_EQUAL=, LOG=, ...,MIN=, MAX=,  OUTLINE=, POLARIZATION=, PREVIEW= ....
99;
100;       *except*: CROP, PXSIZE, PYSIZE, ROT, TRANSPARENT, WINDOW) ]
101;
102;
103; INPUTS:
104;   data
105;
106;
107; OPTIONAL INPUTS:
108;   select
109;
110;
111; KEYWORD PARAMETERS:
112;   GIF=
113;
114;   /KML= if set, a KML file is created with the information necessary to use
115;   the GIF or PNG file.
116;
117;   PNG= png file. Pixels missing or unobserved in the input data will be
118;   totally 'transparent' in the output file.
119;
120;   RESO_ARCMIN = pixel angular size in arcmin (at the equator) of the cartesian
121;   map generated
122;
123;   SUBTITLE = information on the data, will appear in KML file GroundOverlay
124;   description field
125;
126;   TITLEPLOT = information on the data, will appear in KML file GroundOverlay
127;   name field
128;
129; OUTPUTS:
130;
131;
132;
133; OPTIONAL OUTPUTS:
134;
135;
136;
137; COMMON BLOCKS:
138;
139;
140;
141; SIDE EFFECTS:
142;
143;
144;
145; RESTRICTIONS:
146;
147;
148;
149; PROCEDURE:
150;
151;
152;
153; EXAMPLE:
154;
155;
156;
157; MODIFICATION HISTORY:
158;
159;-
160;    COLT=
161;    COORD=
162;    FACTOR=
163;    FLIP=
164;    GRATICULE=
165;    HBOUND=
166;    HELP=
167;    HIST_EQUAL=
168;    IGRATICULE=
169;    LOG=
170;    MAX=
171;    MIN=
172;    NESTED=
173;    NO_DIPOLE =
174;    NO_MONOPLE=
175;    OFFSET=
176;    ONLINE=
177;    OUTLINE=
178;    POLARIZATION=
179;    PREVIEW=
180;    QUADCUBE= ,
181;    SAVE=
182
183
184;TODO : documentation (idl, latex)
185;       check orientation (Google coordinates: Celestial)
186;       transparency: Done
187;
188solve_kw_conflict,'png', 'gif',       k1=png,    k2=gif,   kout=img_file, /defined
189
190if undefined(reso_arcmin) then reso_arcmin = 30.
191pxsize = 360.*60./reso_arcmin
192pysize = 180.*60./reso_arcmin
193
194; Do not allow cartview keywords that are set internally by this routine
195if defined(other_kwds) then begin
196    forbidden = ['CROP','PXSIZE','PYSIZE','ROT','TRANSPARENT','WINDOW']
197    useless =   ['CHARSIZE','FITS','HXSIZE','NOBAR','NOLABELS','NOPOSITION' &
198    'PS','UNITS','XPOS','YPOS']
199    provided = tag_names(other_kwds)
200    for i=0, n_elements(provided)-1 do begin
201        jforb = index_word(forbidden, provided(i))
202        jusel = index_word(useless, provided(i))
203        if jforb ge 0 then begin
204            message,'Keyword '+provided(i)+' ('+forbidden(jforb)+')'+' not allowed.'
205        endif
206        if jusel ge 0 then begin
207            message,/info,'Keyword '+provided(i)+' ('+useless(jusel)+')'+' will be ignored.'
208        endif
209    endfor
210endif
211
212cartview, file_in, select_in, $
213          /CROP, $ ; crop image
214          PXSIZE = pxsize, $
215          PYSIZE = pysize, $
216          ROT=[180,0,0], $ ; rotation constrained by Google Sky
217          /TRANSPARENT, $  ; transparent missing pixels
218          WINDOW = -1, $ ; virtual window
219          gif = gif, $
220          png = png, $
221          reso_arcmin = reso_arcmin, $
222          _strict_extra = other_kwds
223
224if keyword_set(kml) then begin
225    if keyword_set(png) then suff = '.png'
226    if keyword_set(gif) then suff = '.gif'
227    iend = strpos(strlowcase(img_file),suff)
228    if (iend gt 0) then kmlfile = strmid(img_file,0,iend) +'.kml' else kmlfile = img_file +'.kml'
229    write_kml_file, img_file, kmlfile, title=titleplot, subtitle=subtitle
230endif
231
232return
233end
234