File: cgcbar2kml.pro

package info (click to toggle)
coyote 2019.01.29-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster
  • size: 6,316 kB
  • sloc: python: 184; makefile: 14; sh: 13
file content (452 lines) | stat: -rw-r--r-- 21,748 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
; docformat = 'rst'
;
; NAME:
;   cgCBar2KML
;
; PURPOSE:
; This program creates a KML file that can be opened in Google Earth to display a
; color bar as a ScreenOverlay. Screen overlays are images that are displayed in 
; a fixed location on the Google Earth display. A corresponding color bar image file is 
; produced. The KML and color bar image file must be in the same directory to use them with
; Google Earth.
;
;******************************************************************************************;
;                                                                                          ;
;  Copyright (c) 2012, by Fanning Software Consulting, Inc. All rights reserved.           ;
;                                                                                          ;
;  Redistribution and use in source and binary forms, with or without                      ;
;  modification, are permitted provided that the following conditions are met:             ;
;                                                                                          ;
;      * Redistributions of source code must retain the above copyright                    ;
;        notice, this list of conditions and the following disclaimer.                     ;
;      * Redistributions in binary form must reproduce the above copyright                 ;
;        notice, this list of conditions and the following disclaimer in the               ;
;        documentation and/or other materials provided with the distribution.              ;
;      * Neither the name of Fanning Software Consulting, Inc. nor the names of its        ;
;        contributors may be used to endorse or promote products derived from this         ;
;        software without specific prior written permission.                               ;
;                                                                                          ;
;  THIS SOFTWARE IS PROVIDED BY FANNING SOFTWARE CONSULTING, INC. ''AS IS'' AND ANY        ;
;  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES    ;
;  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT     ;
;  SHALL FANNING SOFTWARE CONSULTING, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,             ;
;  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED    ;
;  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;         ;
;  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND             ;
;  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT              ;
;  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS           ;
;  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                            ;
;******************************************************************************************;
;
;+
; This program creates a KML file that can be opened in Google Earth to display a
; color bar as a ScreenOverlay. Screen overlays are images that are displayed in 
; a fixed location on the Google Earth display. A corresponding color bar image file is 
; produced. The KML and color bar image file must be in the same directory to use them with
; Google Earth. In general, any keyword used for horizontal color bars in cgColorbar can
; be used with this program. The colorbar image is made from a PostScript intermediate file, which 
; means ImageMagick must be installed on your computer and available to IDL to run this program 
; successfully. Please see `IDL Output for Web Display <http://www.idlcoyote.com/graphics_tips/weboutput.php>`
; for details.
; 
; .. image:: cgcbar2kml.png
; 
; :Categories:
;    Graphics, FileIO, Maps
;    
; :Keywords:
;    addtofile: in, optional, type=object
;       If this keyword contains a cgKML_File object, the image is added to the file
;       as a <ScreenOverlay> element and a separate KML file is not created. In other
;       words, the `Filename` keyword is ignored and the image file created takes its
;       name from the cgKML_File object.
;    background: in, optional, type=string, default='gray'
;       The background color for the color bar.
;    bottom: in, optional, type=integer, default=0
;       The lowest color index of the colors to be loaded in the color bar.
;    brewer: in, optional, type=boolean, default=0
;         This keyword is used only if the `CTIndex` keyword is used to select a color table number.
;         Setting this keyword allows Brewer color tables to be used.
;    charpercent: in, optional, type=float, default=0.85                 
;       A value from 0.0 go 1.0 that is multiplied by the CHARSIZE to produce
;       the character size for the color bar. This value is only used if CHARSIZE is 
;       undefined. This keyword is primarily useful for using color bars in resizeable 
;       graphics windows (cgWindow).
;    charsize: in, optional, type=float
;       The character size of the color bar annotations. Default is cgDefCharsize()*charPercent.
;    clamp: in, optional, type=float
;        A two-element array in data units. The color bar is clamped to these
;        two values. This is mostly of interest if you are "window-leveling"
;        an image. The clamp is set to the "window" of the color bar.
;        Normally, when you are doing this, you would like the colors outside
;        the "window" to be set to a neutral color. Use the NEUTRALINDEX keyword
;        to set the netural color index in the color bar. (See the Examples section
;        for more information.)
;    color: in, optional, type=string
;        The name of the color to use for color bar annotations. Ignored unless passed 
;        the name of a cgColor color. The default value is to use the ANNOTATECOLOR.
;    ctindex: in, optional, type=integer
;         The index number of a color table. The `Brewer` and `Reverse` keywords will be checked
;         to see how to load the color table into the `Palette` keyword. This keyword will take
;         precidence over any colors that are loaded with the `Palette` keyword. 
;    description: in, optional, type=string
;       A string that is used to describe the image in the Google Earth interface.
;    discrete: in, optional, type=boolean, default=0
;         Set this keyword to configure certain properties of the color bar to make
;         discrete color blocks for the color bar. This works best if you are using
;         a handful of colors in the color bar (e.g, 8-16).
;    divisions: in, optional, type=integer
;         The number of divisions to divide the bar into. There will
;         be (divisions + 1) annotations. The default is 0 if using the
;         default color bar formatting, which allows the plot command to 
;         determine how many divisions to make. Otherwise, if you are specifying
;         some other format for the tick labels, the default number of divisions
;         is six.
;    draworder: in, optional, type=integer, default=0
;        The drawing order of image overlay. The first order is 0. Images with a higher
;        order are drawn on top of images with a lower order.
;    filename: in, optional, type=string, default='kml_cbimage.kml'
;        The name of the KML file that will be created. The image file will have the same name,
;        but with a *.png file extension. The KML file and the image file will be created in the
;        same directory.
;    format: in, optional, type=string, default=""
;       The format of the color bar annotations. Default is "". Note that the
;       formatting behaviour can change, depending up values for the keywords
;       `RANGE` and `DIVISIONS`. If you prefer to let the IDL Plot command determine
;       how the color bar labels are formatted, set the format to a null string and
;       set the `DIVISIONS` keyword to 0. Note the difference in these two commands::
;       
;           cgColorbar, Range=[18,125], Position=[0.1, 0.8, 0.9, 0.85]
;           cgColorbar, Range=[18,125], Position=[0.1, 0.7, 0.9, 0.75], Divisions=0
;    kmz: in, optional, type=boolean, default=0
;        Set this keyword to move the KML file and support files to a KMZ compressed file.
;        Note that this capability is ONLY available in versions of IDL starting with version 8.0.
;    location: in, optional, type=intarr
;       A two-element array giving the location of the top-left corner of the
;       color bar in normalized coordinates from the upper-left of the Google Earth
;       display screen. Default is [0.025, 0.975].
;    maxrange: in, optional
;       The maximum data value for the color bar annotation. Default is NCOLORS.
;    minrange: in, optional, type=float, default=0.0
;       The minimum data value for the bar annotation. 
;    minor: in, optional, type=integer, default=2
;       The number of minor tick divisions. 
;    ncolors: in, optional, type=integer, default=256
;       This is the number of colors in the color bar.
;    neutralindex: in, optional, type=integer   
;       This is the color index to use for color bar values outside the
;       clamping range when clamping the color bar with the CLAMP keyword.
;       If this keyword is absent, the highest color table value is used
;       for low range values and the lowest color table value is used
;       for high range values, in order to provide contrast with the
;       clamped region. (See the Examples section for more information.)
;    oob_factor: in, optional, type=float, default=0.2
;       The default is to make the length of the out-of-bounds triangle the
;       same distance as the height (or width, in the case of a vertical
;       color bar) of the color bar. If you would prefer a shorted triangle length, 
;       set this keyword to a value less than zero (e.g., 0.5). If you prefer a 
;       longer length, set this keyword to a value greater than zero. The "standard"
;       length will be multiplied by this value.
;    oob_high: in, optional, type=string
;       The name of an out-of-bounds high color. This color will be represented
;       by a triangle on the right or top of the color bar. If the color is
;       a string byte value (e.g., "215"), then this color in the current color
;       table is used. The color can also be a three-element color triple 
;       (e.g., [240, 200, 65]).
;    oob_low: in, optional, type=string
;       The name of an out-of-bounds low color. This color will be represented
;       by a triangle on the left or bottom of the color bar. If the color is
;       a string byte value (e.g., "215"), then this color in the current color
;       table is used. The color can also be a three-element color triple 
;       (e.g., [240, 200, 65]).
;    palette: in, optional, type=byte
;       A color palette containing the RGB color vectors to use for the color
;       bar. The program will sample NCOLORS from the color palette. 
;    placename: in, optional, type=string, default='Color Bar'
;        This is the <name> element in a Feature object. It is user-defined text that is used as
;        the label for an object in Google Earth.
;    range: in, optional, type=float
;       A two-element vector of the form [min, max]. Provides an alternative 
;       and faster way way of setting the MINRANGE and MAXRANGE keywords.
;    reverse: in, optional, type=boolean, default=0
;       An alternative keyword name (one I can actually remember!) for the INVERTCOLORS keyword.
;       It reverses the colors in the color bar.
;    tickinterval: in, optional, type=float
;       Set this keyword to the interval spacing of major tick marks. Use this keyword in
;       place of XTickInterval or YTickInterval keywords.
;    ticklen: in, optional, type=float, default=0.25
;       Set this keyword to the major tick length desired. Default is 0.25. Setting this 
;       keyword to a value greater than or equal to 0.5 will result in major tick marks 
;       extending the width of the color bar. Note that setting this keyword to 0.3 or
;       greater will result in minor tick mark lengths being set to 0.01, which is almost 
;       too small to be seen. All direct graphics tick marks act in this (strange!) way.
;    ticknames: in, optional, type=string                 
;       A string array of names or values for the color bar tick marks.
;    title: in, optional, type=string, default=""
;       This is title for the color bar. The default is to have no title.
;    tcharsize: in, optional, type=float
;       The title size. By default, the same as `Charsize`. Note that this keyword is
;       ignored for vertical color bars unless the title location (`TLocation`) is on
;       the opposite side of the color bar from the color bar labels. This is a consequence
;       of being upable to determine the length of color bar labels programmatically in this
;       orientation.
;    width: in, optional, type=integer, default=300
;       The width, in pixels, of the colorbar image that is created.
;    xlog: in, optional, type=boolean, default=0
;       Set this keyword to use logarithmic scaling for the colorbar data range.
;    xtickinterval: in, optional, type=float
;       This keyword is trapped, but unused. Please use the`TickInterval` keyword instead.
;    xtitle: in, optional, type=string
;        This keyword is ignored. Use the `Title` keyword to set a title for the color bar.
;    _ref_extra: in, optional
;         Any keyword appropriate KML screen overlay objects is allowed.
;
; :Examples:
;    Here is how you can put an AVHRR NDVI image of Africa on a Google Earth display
;    with a color bar:: 
;    
;       ;; Download the image file from the Coyote web page.
;       netObject = Obj_New('IDLnetURL')
;       url = 'http://www.idlcoyote.com/data/AF03sep15b.n16-VIg.tif'
;       returnName = netObject -> Get(URL=url, FILENAME='AF03sep15b.n16-VIg.tif')
;       Obj_Destroy, netObject
;       
;       ;; Create the image overlay KML file.
;       kmlFile = Obj_New('cgKML_File', 'avhrr_ndvi_cb.kml')
;       cgLoadCT, 11, /Brewer, /Reverse, RGB_Table=palette
;       map = cgGeoMap('AF03sep15b.n16-VIg.tif', Image=image)
;       scaledImage = BytScl(image > 0)
;       cgImage2KML, scaledImage, map, $
;          Palette=palette, Missing_Value=0, $
;          Description='AVHRR NDVI Data from Africa', $
;          PlaceName='AVHRR Africa', $
;          AddToFile=kmlFile
;       cgCBar2KML, Palette=palette, Range=[0,9400], $
;          Title='NDVI Index', $
;          Description='AVHRR NDVI Color Bar', $
;          PlaceName='NDVI Color Bar', $
;          AddToFile=kmlFile
;       kmlFile -> Save
;       kmlFile -> Destroy
;          
;       ;; Start Google Earth and open the KML file you just created.
;       
;    The output should look like the figure above.
;    
;    If you just wish to create a KML file with a color bar, you can do this::
;    
;       cgCBar2KML, Filename='colorbar.kml', CTIndex=5, Title='Test Color Bar'
;       
; :Author:
;    FANNING SOFTWARE CONSULTING::
;       David W. Fanning 
;       1645 Sheely Drive
;       Fort Collins, CO 80526 USA
;       Phone: 970-221-0438
;       E-mail: david@idlcoyote.com
;       Coyote's Guide to IDL Programming: http://www.idlcoyote.com
;
; :History:
;     Change History::
;        Written, 30 October 2012 by David W. Fanning.
;        Added DRAWORDER keyword and fixed a typo concerning MISSING_VALUE. 31 Oct 2012. DWF.
;        Have been writing the absolute path to the image file into the KML file, when I should
;            have been using a relative path. 22 Feb 2013. DWF.
;
; :Copyright:
;     Copyright (c) 2012-2013, Fanning Software Consulting, Inc.
;-
PRO cgCBar2KML, $
    ADDTOFILE=addtofile, $
    BACKGROUND=background, $
    BOTTOM=bottom, $
    BREWER=brewer, $
    CHARPERCENT=charpercent, $
    CHARSIZE=charsize, $
    CLAMP=clamp, $
    COLOR=color, $
    CTINDEX=ctindex, $
    DESCRIPTION=description, $
    DISCRETE=discrete, $
    DIVISIONS=divisions, $
    DRAWORDER=draworder, $
    FILENAME=filename, $
    FORMAT=format, $
    KMZ=kmz, $
    LOCATION=location, $
    MAXRANGE=maxrange, $
    MINOR=minor, $
    MINRANGE=minrange, $
    NCOLORS=ncolors, $
    NEUTRALINDEX=neutralIndex, $
    OOB_FACTOR=oob_factor, $
    OOB_HIGH=oob_high, $
    OOB_LOW=oob_low, $
    PALETTE=palette, $
    PLACENAME=placename, $
    RANGE=range, $
    REVERSE=reverse, $
    TCHARSIZE=tcharsize, $
    TICKINTERVAL=tickinterval, $
    TICKLEN=ticklen, $
    TICKNAMES=ticknames, $
    TITLE=title, $
    XLOG=xlog, $
    XTICKINTERVAL=xtickinterval, $ ; Ignored.
    XTITLE=xtitle, $ ; Ignored.
    WIDTH=width, $
    _REF_EXTRA=extra
    
    Compile_Opt idl2
    
    Catch, theError
    IF theError NE 0 THEN BEGIN
       Catch, /CANCEL
       void = cgErrorMsg()
       RETURN
    ENDIF 
    
    ; Default values.
    IF N_Elements(background) EQ 0 THEN background = 'gray'
    IF N_Elements(location) EQ 0 THEN location = [0.025, 0.975]
    IF N_Elements(placename) EQ 0 THEN placename = 'Color Bar'
    IF N_Elements(oob_factor) EQ 0 THEN oob_factor = 0.2
    IF N_Elements(charsize) EQ 0 THEN charsize=1.75
    IF N_Elements(tcharsize) EQ 0 THEN tcharsize = 2.0
    IF N_Elements(title) EQ 0 THEN BEGIN
        position = [0.1, 0.425, 0.9, 0.775]
    ENDIF ELSE BEGIN
        position = [0.1, 0.525, 0.9, 0.875]
    ENDELSE
    
    ; If the KMZ keyword is set, make sure this version of IDL supports it.
    IF Keyword_Set(kmz) THEN BEGIN
        IF Float(!Version.Release) LT 8.0 THEN BEGIN
            Message, 'The KMZ keyword is not supported in this version of IDL.', /Informational
            kmz = 0
        ENDIF
    ENDIF
    
    ; Need a filename?
    IF N_Elements(filename) EQ 0 THEN BEGIN
       CD, CURRENT=thisDir
       filename = Filepath(ROOT_DIR=thisDir, 'kml_cbimage.kml')
    ENDIF
   
    ; Construct the image filename
    rootName = cgRootName(filename, DIRECTORY=thisDir, EXTENSION=ext)
    IF StrUpCase(ext) NE 'KML' THEN Message, 'The output filename must have a KML file extension.'
    imageFilename = Filepath(ROOT_DIR=thisDir, rootname + '.png')
    
   IF cgObj_Isa(addtofile, 'cgKML_File') THEN BEGIN
   
      addToFile -> GetProperty, FILENAME=filename, COUNT=count
      rootname = cgRootName(filename, DIRECTORY=thisDir, EXTENSION=ext)
      imageFilename = FilePath(ROOT_DIR=thisDir, rootname + StrTrim(count+1,2) + '.png')
      
     ; Write the image file.
     rootname = cgRootName(imageFilename, DIRECTORY=thisDir)
     psFileName = Filepath(ROOT_DIR=thisDir, rootname + '.ps')
     cgPS_Open, psFilename, /Quiet
     cgDisplay, 1000, 200
     cgColorFill, [0,1,1,0,0], [0,0,1,1,0], /Normal, Color=background
     cgColorbar, $
        BOTTOM=bottom, $
        BREWER=brewer, $
        CHARPERCENT=charpercent, $
        CHARSIZE=charsize, $
        CLAMP=clamp, $
        COLOR=color, $
        CTINDEX=ctindex, $
        DISCRETE=discrete, $
        DIVISIONS=divisions, $
        FORMAT=format, $
        MAXRANGE=maxrange, $
        MINOR=minor, $
        MINRANGE=minrange, $
        NCOLORS=ncolors, $
        NEUTRALINDEX=neutralIndex, $
        OOB_FACTOR=oob_factor, $
        OOB_HIGH=oob_high, $
        OOB_LOW=oob_low, $
        PALETTE=palette, $
        POSITION=position, $
        RANGE=range, $
        REVERSE=reverse, $
        TCHARSIZE=tcharsize, $
        TICKINTERVAL=tickinterval, $
        TICKLEN=ticklen, $
        TICKNAMES=ticknames, $
        TITLE=title, $
        XLOG=xlog
     cgPS_Close, /PNG, /DELETE_PS, WIDTH=width, /NoMessage
     
     ; Create the screen overlay object if a raster file was created.
     IF File_Test(imageFilename) THEN BEGIN
       overlay = Obj_New('cgKML_ScreenOverlay', $
            HREF=File_Basename(imageFilename), $
            DESCRIPTION=description, $
            DRAWORDER=draworder, $
            SCREEN_XY=location, $
            PLACENAME=placename)
        addToFile -> Add, overlay
      ENDIF
   
   ENDIF ELSE BEGIN
   
     ; Write the image file.
     rootname = cgRootName(imageFilename, DIRECTORY=thisDir)
     psFileName = Filepath(ROOT_DIR=thisDir, rootname + '.ps')
     cgPS_Open, psFilename, /Quiet
     cgDisplay, 1000, 200
     cgColorFill, [0,1,1,0,0], [0,0,1,1,0], /Normal, Color=background
     cgColorbar, $
        BOTTOM=bottom, $
        BREWER=brewer, $
        CHARPERCENT=charpercent, $
        CHARSIZE=charsize, $
        CLAMP=clamp, $
        COLOR=color, $
        CTINDEX=ctindex, $
        DISCRETE=discrete, $
        DIVISIONS=divisions, $
        FORMAT=format, $
        MAXRANGE=maxrange, $
        MINOR=minor, $
        MINRANGE=minrange, $
        NCOLORS=ncolors, $
        NEUTRALINDEX=neutralIndex, $
        OOB_FACTOR=oob_factor, $
        OOB_HIGH=oob_high, $
        OOB_LOW=oob_low, $
        PALETTE=palette, $
        POSITION=position, $
        RANGE=range, $
        REVERSE=reverse, $
        TCHARSIZE=tcharsize, $
        TICKINTERVAL=tickinterval, $
        TICKLEN=ticklen, $
        TICKNAMES=ticknames, $
        TITLE=title, $
        XLOG=xlog
     cgPS_Close, /PNG, /DELETE_PS, WIDTH=width, /NoMessage
   
     ; Write the KML file.
     kmlFile = Obj_New('cgKML_File', filename)
     
     ; Create the screen overlay object if a raster file was created.
     IF File_Test(imageFilename) THEN BEGIN
       overlay = Obj_New('cgKML_ScreenOverlay', $
            HREF=File_Basename(imageFilename), $
            DESCRIPTION=description, $
            DRAWORDER=draworder, $
            SCREEN_XY=location, $
            PLACENAME=placename)
        kmlFile -> Add, overlay
      ENDIF
     kmlFile -> Save, KMZ=Keyword_Set(kmz)
     kmlFile -> Destroy
     
   ENDELSE

END