 |
 |
|
||||
 |
 |
StormLab Customized Overlay
File Standards V4.0.4
Overview:
Open source GIS (geographic information systems) in StormLab 4.0 allows
intermediate to
advanced users to easily develop and freely distribute
customized overlays for the software. StormLab uses
a modified adaptation of the
file format initially established by AllisonHouse Inc. LLC. The file
specifications
are detailed below.
Disclaimer:
Storm Alert Inc. agrees to display customized overlay files meeting the
specified format that follows.
Storm Alert Inc. will provide limited
troubleshooting for such files, and it is up to the file’s author to ensure
that they
are in the proper format. The file author assumes all responsibility
for the file contents. Users should ensure that
they are using and/or
distributing data sets that are clearly marked as free access with no
copyrights, trademarks
or other restrictions. Storm Alert Inc. will gladly
cooperate with any persons/companies whose rights have been violated.
1.) File format.
a. Files are to be created in Microsoft Windows
b.
Files should contain only standard characters and punctuation with
standard carriage returns/line
feeds (here on abbreviated as <CRLF>
c. Files should not contain any special formatting other than the specified protocol describe here.
d.
Files should be placed in the StormLab\OverlayData directory for
consistency and troubleshooting
purposes.
2.)
Data Header Format:
Line 1 (Download Only): Refresh:
X<CRLF> , where X is the minimum refresh interval of this file,
in minutes.
This refresh interval is only required by non-local files which are
routinely downloaded, such as those for
meteorological data. Those generating
live data via online PHP scripts or other means should include this
tag if it is
necessary to limit bandwidth access to this specific file.
Line 2 (Optional) Title: TEXT HERE<CRLF> , specifies a title for the user to identify the contents of
the
document. This is for user use only and is not used by StormLab.
Line 3 (Optional) Underlay: ANY TEXT<CRLF> , instructs StormLab whether this overlay should be plotted underneath the radar imagery (default is over). VERSION 4.0.1 AND HIGHER REQUIRED. The presence of the "Underlay:" tag will instruct the software to render the data as an underlay. The text after the tag is arbitrary (yes, true, 1, whatever).
Line 4 (Download Only) Filename:
filename_{SITEINFO}.txt<CRLF> ,
specifies the local filename for
a given customized overlay file. Since local
overlay files will already exist on the user’s computer in the
\OverlayData
directory, this entry is not required for such files. For downloaded data, this
filename can
be anything, although a .txt extension is recommended for
simplicity. If the file is radar-site specific, used
to reduce overhead for
large file sizes, the user will include the phrase {SITEINFO} in the filename, which
is changed upon receipt to that
radar site. For example, if a data server is instructed to create a dynamic
overlay file for radar site “keax”, then the example Filename: overlaydata_{SITEINFO}.txt would be
stored by
StormLab as StormLab\OverlayData\overlaydata_keax.txt
Line 5 (Optional): IconFile: A, B, C, D, E, F<CRLF>
StormLab has the ability to plot icons contained in icon file sheets. An icon sheet
is basically a graphics file (such as a .png) containing equally spaced icons. It is
encouraged that you use transparent
png’s to create your icons, offering the smallest size and
greatest
flexibility.
A
= A number indicating a key to reference this icon file later in the
document. For the first IconFile:
entry in this document, A will be 1.
For the second IconFile: entry, A
would be 2, and so on.
B = The width, in pixels of each icon in the file.
C = The height, in pixels of each icon in the file.
D
= Assuming that 0,0 marks the top/left corner of each icon, this item
represents the number of pixels
to the right corresponding to the center or
rotation point of an icon. The icon will be drawn with this
pixel as the center.
E
= Assuming that 0,0 marks the top/left corner of each icon, this item
represents the number of pixels
down corresponding to the center or rotation
point of an icon. The icon will be drawn with this pixel as
the center.
F
= The website containing your icon file. StormLab will only download
the file once, and check it
again roughly once an hour to see if its contents
have changed. Files are stored in the \Icons subdirectory.
For example:
IconFile: 1, 22, 36, 4, 35, “http://www.blah.com/icons/stormcell.png"
This tells StormLab that the 1st
icon file can be found at the website above. It will be stored
locally at
\Icons\stormcell.png. Each icon is 22 pixels wide and 36 pixels tall. So, if
this file contained
3 rows of icons with 4 icons in each row, we should be
expecting a filesize that is 88 pixels wide and
108 pixels tall.
When plotted, StormLab will position
each icon such that the point 4 pixels to the right and 35 pixels
down is
centered at the location specified in the Object:
section later in this document.
Line 6 (Blank line) <CRLF>
3.)
Drawing Polygons (used to create 2 or more point line segment)
Line 1: PolyLine:
A = Red color of line (0 to 255)
B = Green color of line (0 to 255)
C = Blue color of line (0 to 255)
D = Pixel width of line (a number greater or equal to 0)
E = Drop Shadow (0 for no, 1 for yes)
F = Red color of polyline fill (0 to 255)
G = Green color of polyline fill (0 to 255)
H = Blue color of polyline fill (0 to 255)
I = Fill Opacity (0 : transparent to 100: opaque). Zero implies no fill.
J = [OPTIONAL] MinZoom = A number specifying the minimum zoom level to display this information.
If
the final optional setting is missing:
(PolyLine: A, B, C, D, E, F, G, H, I<CRLF>)
StormLab will use the default minimum
zoom setting specified in the Map and Data
Overlays portion of the setup GUI for
this file.
If
the final optional setting is present:
Values:
1 = This polyline will show up at all zoom levels
2 = This polyline will show up at zoom level 2x and higher
4 = This polyline will show up at zoom level 4x and higher
8 = This polyline will show up at zoom level 8x and higher
16 = This polyline will show up at zoom level 16x and higher
32 = This polyline will show up at zoom level 32x and higher
64 = This polyline will show up at zoom level 64x and higher
128 = This polyline will show up at zoom level 128x and higher
For example: PolyLine: 255, 0, 0, 2, 1, 96, 0, 0, 30, 2
would tell StormLab to create a red
line that is 2 pixels wide, drop shadowed, and with a 30% opaque
fill of dark
red. This line will only show up at zoom scale 2x and higher.
For example: PolyLine: 0, 0, 255, 1, 0, 0, 0, 0, 0
would tell StormLab to create a blue
line that is 1 pixels wide, no drop shadow, and with no fill. Because
the last
item missing, StormLab will draw this line based on the default minimum zoom
settings contained
in the Map and Data Overlay settings for this file.
Line 2: (Indented 3 spaces for
clarity) Lat/Lon:
Lat1,Lon1,Lat2,Lon2, etc…<CRLF>
Contains all the latitude/longitude
pairs, separated by commas that define the polyline. Do not use spaces
between
the data points. Also, Do not forget to include minus signs for longitudes in
the US.
NOTE:
More than one Lat/Lon: data line
may appear in a polyline block to represent discontinuous areas,
such as two
separate slight risk thunderstorm areas for example.
Line 3 (Optional): (Indented 3 spaces for clarity) Text:
"Plotted Text"[,X,Y]<CRLF>
Contains text to be plotted at each
location specified in any Lat/Lon:
sections. Text will be plotted using
the last found Font: section, or as a default, 8 point Arial font, bold, with the
same color as the polyline.
X
and Y are optional. If present, they represent the offset, in pixels, from the
last latitude and
longitude to plot this text. X =
left/right and Y= up/down.
Line 4 (Optional): (Indented 3 spaces for clarity) Title: “TEXT HERE”<CRLF>
StormLab can provide a mouse sampled
pop-up for each lat/lon pair described above. This sample can
contain a bold
title, sample text, and a link to additional information online. The sample
title in this section
tells the user which data point has been sampled, and may
be something along the lines of
Title:
“SPC Day 1 Outlook”
Line 5 (Optional): (Indented 3 spaces
for clarity) Sample:
“This is line 1 of sample text.\nThis is line 2
of sample text”<CRLF>
This section contains optional sample
text for the pop-up dialog described above. Note the use of
the \n
characters above. These should be used to specify required line feeds in the
popup window.
For example, using the title and sample
example above, the popup should show:
SPC Day 1
Outlook
This is line 1 of sample text
This is line 2 of sample text
Line 6
(Optional): (Indented 3 spaces for clarity) Link: http://www.website.com<CRLF>
This section contains an optional
website link for the pop-up dialog described above. When clicked,
the default
Windows web browser will be launched to the listed URL. A good example
continuing the
above theme would be Link:
http://www.spc.noaa.gov/products/outlook/day1otlk.html
Line Last: End: Terminates the PolyLine block.
4.)
Plotting Icons
Line 1: Object:[MinZoom]<CRLF>
This tag establishes that the following
sequence of data pertains to plotting pre-created graphics
contained in files
located in the StormLab\Icons directory.
MinZoom
is optional. If present, it must be one of the values below. In this
case, StormLab will only
proceed in rendering this object at the zoom levels at
least as high as this number.
1 = This object will show up at all zoom levels
2 = This object will show up at zoom level 2x and higher
4 = This object will show up at zoom level 4x and higher
8 = This object will show up at zoom level 8x and higher
16 = This object will show up at zoom level 16x and higher
32 = This object will show up at zoom level 32x and higher
64 = This object will show up at zoom level 64x and higher
128 = This object will show up at zoom
level 128x and higher
Object:16 would tell StormLab to
only plot this icon at 16x zoom or higher.
This could be very useful in creating progressive zoom objects like roadway
icons.
Line 2: (Indented 3 spaces for
clarity) Lat/Lon:
Lat1,Lon1<CRLF>
Contains the latitude/longitude
location at which to render this object. Do not use spaces between
the data
points. Also, do not forget to include minus signs for longitudes in the US.
Line 3 (Indented 3 spaces for clarity) Icon:
A,B,CCC,D,E<CRLF>
Contains information specific to the icon we are plotting.
A:
A number specifying the X (east/west) pixel offset to plot this icon from
the longitude
contained in Line 2. TYPICALLY 0
B:
A number specifying the Y (north/south) pixel offset to plot this icon from
the latitude
contained in Line 2. TYPICALLY 0
C:
A *3 digit* number (000 to 359) contained the degrees in which to rotate the
icon about
its center point. 000 =
up/north, 090 = right/east, 180 = down/south,
270 = west/left. Useful for
plotting icons such as wind barbs or GPS bearing
icons.
D:
A number specifying which icon file (described back in section 2 – Data
Header Format) contains the
graphic to be plotted.
E:
A number specifying which icon in the file described in item D is to be
plotted. The icon count
starts at 1 in the top/left corner of the file and works
toward the right across each row. For example,
a file containing 12 icons, 4 in
each row would look like:
1 2 3 4
5 6 7 8
9
10
11
12
Line 4 (Optional): (Indented 3 spaces for clarity) Text:
"Plotted Text"[,X,Y]<CRLF>
Contains text to be plotted at each
location specified in the Lat/Lon:
section above. Text will be plotted
using the last found Font: section, or as a default, 8 point Arial font, bold, black.
X
and Y are optional. If present, they represent the offset, in pixels, from the
last latitude and
longitude to plot this text. X =
left/right and Y= up/down.
An example of where this might be used
would be to plot a route number inside an interstate icon.
Line 5 (Optional): (Indented 3 spaces for clarity) Title: “TEXT HERE”<CRLF>
StormLab can provide a mouse sampled
pop-up for each object described above. This sample can
contain a bold title,
sample text, and a link to additional information online. The sample title in
this section
tells the user which data point has been sampled, and may be
something along the lines of
Title
Line 6 (Optional): (Indented 3 spaces
for clarity) Sample:
“This is line 1 of sample text.\nThis is line 2 of
sample text”<CRLF>
This section contains optional sample
text for the pop-up dialog described above. Note the use of
the \n
characters above. These should be used to specify required line feeds in the
popup dialogue.
For example, using the title and sample example above, the popup
should show:
SPC
Day 1 Outlook
This is line 1 of sample text
This is line 2 of sample text
Line 7
(Optional): (Indented 3 spaces for clarity) Link: http://www.website.com<CRLF>
This section contains an optional
website link for the pop-up dialog described above. When clicked,
the default
Windows web browser will be launched to the listed URL. A good example
continuing the
above theme would be Link:
http://www.spc.noaa.gov/products/outlook/day1otlk.html
Line Last: End: Terminates the Object block.
5.)
Plotting Text
Font:
FontName,FontSize,FontBold,FontEffects,R,G,B<CRLF>
Anytime a Font: tag is found in the document, the current drawing font will be
switched to the
information above.
FontName =
Any usable font name – e.g. Arial
FontSize = A number containing the font size – e.g. 9
FontBold = 0 = normal, 1 = bold
FontEffects = 0 = none, 1 = dropshadow, 2 = outline, 3 = strong outline
R = A number (0-255) containing the red color of the font
G = A number (0-255) containing the green color of the font
B = A number (0-255) containing the blue color of the font
Text:
TextOutput,MinZoom,Lat1,Lon1,Lat2,Lon2,etc…<CRLF>
Anytime a Text: tag is found, text will be output to the screen, centered on
the lat/lon pairs that follow.
All Text: tags
should be preceded by a Font: tag
somewhere in the document (Remember: Arial, 8,
bold, black is the default)
TextOutput = The text to be output to the screen (could be a city, radar site, airport, whatever)
MinZoom = A number specifying the minimum zoom level to display this information.
Values:
99
= StormLab will use the default minimum zoom setting specified in the
Map and Data Overlays
portion of the setup for this file.
1 = This text will show up at all zoom levels
2 = This text will show up at zoom level 2x and higher
4 = This text will show up at zoom level 4x and higher
8 = This text will show up at zoom level 8x and higher
16 = This text will show up at zoom level 16x and higher
32 = This text will show up at zoom level 32x and higher
64 = This text will show up at zoom level 64x and higher
128 = This text will show up at zoom level 128x and higher
Lat = A decimal number containing the latitude on which the font should be centered.
Lon
= A decimal number containing the longitude on which the font should
be centered (make sure that
you include a negative number
Example:
Text: My House,64,40.00,-95.00,35.00,-100.00
When a radar image is zoomed in to 64x
or higher, StormLab will plot the text “My House” at locations
40N, -95W as well as 35N and -100W
FixedText:
TextOutput,MinZoom,X,Y<CRLF>
Anytime a FixedText: tag is found, text
will be output to the screen, anchored to the X, Y coordinates provided. X
and Y are pixels to the right down from the top left corner of the screen.
This the FixedText tag is not radar site dependent and is useful for
plotting fixed text on screen.
NOTE: The use of a negative X or Y is
permitted and will anchor the text that many pixels from the right or
bottom respectively.
All FixedText: tags should be
preceded by a Font: tag
somewhere in the document (Remember: Arial, 8, bold, black is the
default)
TextOutput = The text
to be output to the screen. Commas are permitted.
MinZoom =
A number specifying the minimum zoom level to display this
information.
Values:
99 =
StormLab will use the default minimum zoom setting specified in the
Map and Data Overlays
portion of the setup for this file.
1 = This text will show up at all zoom levels
2 = This text will show up at zoom level 2x and higher
4 = This text will show up at zoom level 4x and higher
8 = This text will show up at zoom level 8x and higher
16 = This text will show up at zoom level 16x and higher
32 = This text will show up at zoom level 32x and higher
64 = This text will show up at zoom level 64x and higher
128 = This text will show up at zoom level 128x and higher
X =
A whole number specifying the number of pixels from the left (right if
negative) of the radar window that the text should be plotted
Y =
A whole number specifying the number of pixels from the top (bottom if
negative) of the radar windows that the text should be plotted.
Example:
FixedText: Chase Targer: Kansas City, MO,1,10,10
Will plot the text
'Chase Target: Kansas City, MO' at all zoom levels. The text will be
rendered starting at 10 pixels from the left and 10 pixels from the top
(in the upper left
portion of the radar screen).
Location:
TextOutput,MinZoom,Lat1,Lon1,Lat2,Lon2,etc…<CRLF>
Anytime a Location: tag is found, text will be output to the screen. Unlike the
Text:
tag, the location tag will place a dot centered on the lat/lon pairs that
follow with the actual text
offset from this dot. All Text: tags must be preceded by a Font: tag somewhere in the document. The
location dot will also use
the same color as the font.
TextOutput = The text to be output to the screen (could be a city, radar site, airport, whatever)
MinZoom = A number specifying the minimum zoom level to display this information.
Values:
99
= StormLab will use the default minimum zoom setting specified in the
Map and Data Overlays
portion of the setup GUI for this file..
1 = This location will show up at all zoom levels
2 = This location will show up at zoom level 2x and higher
4 = This location will show up at zoom level 4x and higher
8 = This location will show up at zoom level 8x and higher
16 = This location will show up at zoom level 16x and higher
32 = This location will show up at zoom level 32x and higher
64 = This location will show up at zoom level 64x and higher
128 = This location will show up at zoom level 128x and higher
Lat = A decimal number containing the latitude on which the location dot should be centered
Lon
= A decimal number containing the longitude on which the located dot
should be centered (make
sure that you include a negative number).
Example:
Location: KEAX,1,38.8103,-94.2478
At any zoom level (1x and higher),
StormLab will plot the location KEAX at 38.8103N and -94.2478W,
looking sort of
like the following.
·
KEAX
6.) Plotting Circles
It may become desirable to draw a circle in addition to the polyline feature near the top of the document.
Circle:
Lat,Lon,Units,Radius,R,G,B,DropShadow,Thickness,MinZoom<CRLF>
Anytime a Circle: tag is found, a circle will be drawn on the screen with the following options
Lat = A decimal number containing the latitude on which the location dot should be centered
Lon = A decimal number containing the longitude on which the located dot should be centered (make sure that you include a negative number).
Units =
0 – radius is in nautical miles, 1
– radius is in miles, 2 – radius is in
kilometers
Radius – The radius of the circle as defined by the Units above.
R = A number (0-255) containing the red color of the circle
G = A number (0-255) containing the green color of the circle
B = A number (0-255) containing the blue color of the circle
DropShadow = 0 for no, 1 for a drop-shadowed circle
Thickness = The line thickness of the circle
MinZoom = A number specifying the minimum zoom level to display this information.
Values:
99 = StormLab will use the default minimum zoom setting specified in the Map and Data Overlays portion of the setup for this file.
1 = This location will show up at all zoom levels
2 = This location will show up at zoom level 2x and higher
4 = This location will show up at zoom level 4x and higher
8 = This location will show up at zoom level 8x and higher
16 = This location will show up at zoom level 16x and higher
32 = This location will show up at zoom level 32x and higher
64 = This location will show up at zoom level 64x and higher
128 =
This location will show up at
zoom level 128x and higher
Example:
Circle: 39.2,-95.9,0,50,255,255,255,1,3,1
Webmaster: General Site Disclaimer
