Home page | about c-squares | latest news | resources | specification | c-squares mapper | examples

CMAR c-squares Mapper - Technical Information

The CSIRO Marine and Atmospheric Research (CMAR) c-squares mapper is a perl utility which plots dataset exents (geographic "footprints") on a range of base maps, selected automatically according to the extent of the dataset. It operates on "c-squares strings" as supplied by relevant data sources (e.g. metadata records). C-squares are unique identifiers for 10, 5, 1, 0.5, or 0.1 degree squares on the earth's surface (or smaller as desired), numbered according to a convention derived from the World Meteorological Organisation (WMO) 10-degree square numbers and a hierarchical subdivision of the same. C-squares strings are text strings that comprise a list of relevant c-square numbers separated by a vertical bar ( | ) character (example: 1000|1001|1002 etc.). For further information on the c-squares system and nomenclature, see the c-squares home page.

Mapper Features

• Accepts one, or multiple (up to seven) c-square strings for rendering on appropriate base maps. Each string can comprise one to an unlimited number (limited in the software to less than 1 million) of square codes, separated by the vertical bar or pipe (|) character (example: 1000|1001|1002 etc.). Each string can be rendered in a separate colour and/or can be a different resolution (square size) from other strings; however, all codes within a string must be the same resolution and will be plotted identically.
  
  
• Squares can be any from the available set of c-square resolutions, i.e. 10 degree, 5 degree, 1 degree, half degree, 0.1 degree, etc. The resolution (square size) is represented by the length of the individual c-square code e.g. 1000 (10 degree square), 1000:1 (5 degree square), 1000:100 (1 degree square), 1000:100:1 (half degree square), etc.
  
  
• Colours for individual c-squares strings are user definable (hex) colours, e.g. FF00FF (will give a purple square), FF9900 (will give an orange square). A set of seven pre-defined colours can also be addressed by name, viz. red, blue, yellow, black, brown, white, green. If no user definitions are sent, a set of default colours (red through brown) will be used.
  
  
• C-squares may be sent to the mapper in a compressed state and are decompressed by the mapper. Example: 1000:* may be sent instead of the four squares 1000:1 through 1000:4 ; 1000:*** may be sent instead of the one hundred squares 1000:100 through 1000:499 (saving transmission time and bandwidth, since all squares are sent to the mapper in the first instance, and are also returned along with the map to enable subsequent requests e.g. for different choice or size of base map etc.)
  
  
• When called by HTTP "POST" (recommended method), the mapper will potentially cope with unlimited numbers of squares (has been tested with upwards of 100,000 squares without problem on a suitable fast server). The only limitation may be the timeout settings of the host machine, web gateway, or browser client if processing is slow.
  
  
• The c-square codes are checked for validity and the mapper will return informative error messages if a bad code or string segment is detected.
  
  
• The mapper will by default render the supplied squares on a "best fit" base map (with user option to change to other maps as desired), however this can be overridden if the client supplies the file name of the desired map for rendering.
  Note: previous to version 3 the human-readable name of map as viewed in the drop down box was used; for version 3 and onwards, the filename (example: "worldmap_default.jpg") is used instead.
  
  
• Maps can be drawn in two sizes, "normal" (suggested up to 600 pixels wide) and "large". Large maps are also drawn as needed from very large "world" base maps, but are resized and returned to the user as 900 pixels wide. The large "world" base maps support the new (v3) "Globe views" functionality that will permit consistent and seamless panning and zooming to any part of the Earth's surface. The default size is "normal", however the user or remote application can request a large size starting map if desired.
  
  
• "Globe views" can be created from any world base map, presenting (by default) images of the "earth from space" from any viewpoint (i.e., latitude-longitude position, with a number of continents, oceans, poles offered as defaults), that can then be zoomed in through a seven-step range. Images at any zoom step can also be "nudged" in one of eight separate directions, by user-selectable steps of 30, 15, 6, 3 or 2 degrees. (For examples of these and other features refer http://www.obis.org.au/admin/csquares/help.html).
• Land masking - where supported, portions of plotted squares on land will be masked out when this feature is activated. (E.g., useful for distribution maps of marine-only phenomena, to avoid overwriting of the coastline). This facility is not currently available for every base map, although it is available for all "world" maps and many of the pre-zoomed versions.
  
  
• If supplied with a "redirect" URL, the mapper will create an "active" (clickable) map. Clicking on the active map will open a new window which is directed to the previously supplied redirect URL plus the variables N_lat, S_lat, W_long and E_long, which form a bounding box at the input resolution determined by the first c-square sent, and can be further handled by a suitable script created by the remote application developer. See: http://www.cmar.csiro.au/csquares/mapper-tech.htm. This new window can be requested either as full screen (default) or as a small "pop-up" window.
• The map images themselves can be tagged by inserting a user supplied custom identifier if desired, to assist automated harvesting and collation.
• Individual c-squares can be rendered as a rectangle (default) or a solid coloured ("filled") square, upon request. This feature can be applied to different supplied c-square strings independently.
  
• The default behaviour of the mapper to enlarge the smallest squares to improve readability, also to create a 1 pixel border between adjacent squares; can be switched off to depict a more accurate representation. For "world" base maps, also the "globe views" based upon them, this is represented as "visibility = bold"; two more settings ("intermediate", "finest") support progressive thinning of the square borders which may suit intermediate to high levels of zoom better than the "bold" setting.
  
  
• Supports user supplied map title, header, and legend which will be rendered above and below the map as appropriate (may be HTML).
  
  
• The variable "header" can contain HTML and is rendered at the top of the page and also in the browser title. The mapper strips HTML tags from the variable "header", inserting only the remaining text into the HTML head->title tag.
  
  
• CSS style sheets are now in place for printing and display.
  
  
• Javascript functions are included for the popup window creation and Flash enabled browser detection etc.
  
  
• Although the mapper is most suitably called via HTTP POST for application-level use (supports spaces in variable text, long variables, etc.,), however it can also be called via a direct URL with embedded variables for testing and simple mapping actions.
  
  
• Correctly handles Pacific centred world maps (i.e., with borders at 0 degrees E/W as opposed to 180 degrees E/W), if these are selected.
  
  
• Map creation time, plus number of squares processed, is automatically captured and displayed with each map (useful for monitoring system performance, etc.).
  
  
• Can be used to generate inline maps (returns a graphic only, without surrounding HTML wrapper) on request, for embedding into a client application's web page.
  
  
• The size and position of popup windows (used for "click on a map" functionality) are user specifiable.
  
  
• The "click on a map" function can be engaged without requiring the mapper to create any maps, making the application suitable for processing of many standalone spatial search interfaces for web use (for examples, see http://www.cmar.csiro.au/marlin/csq-chooser.htm and http://www.obis.org.au/data_search/mapsearch.html).

Input parameters supported

For the application developer or otherwise interested person, here is the list of currently supported input parameters and their usage.

csq	C-squares string to plot, as a vertical bar (pipe) separated list of valid c-squares codes (this is the only required parameter for cs_map.pl). Example: 1000:1 (single square) or 1000:1|1000:2|1000:3 (three squares). Tip: to create a blank map, send a c-square code of the correct resolution but entirely zeros, e.g. 0000 (10 deg. resolution), 0000:0 (5 deg. resolution), etc.
fill	create filled, rather than outline, squares if any value supplied (e.g. fill=Y) - default is outline.
color	colour of c-square symbol expressed as hex RGB code (e.g. purple: CC66FF) or by name (one of red, green, blue, black, white, yellow, brown). Default is red for csq if no color specified.
csq2 through csq7	optional slots for second, third, fourth, fifth, sixth, and seventh c-squares strings - e.g. for different colours/ resolutions/ symbology, as required
fill2 through fill7	fill the square of the relevant c-squares string if any value supplied (e.g. fill2=Y)
color2 through color7	colour of c-square symbol expressed as hex RGB code or by name (from pre-defined list only), for the relevant c-squares strings. Defaults are green, blue, black, white, yellow, brown. If not supplied, defaults will be used, e.g. green for csq2, etc.
test	lat,lon list of test points, separated by a vertical bar (|) - used for calibrating maps, debugging, etc. (will plot as cross hairs)
header	dataset head and body title (HTML tags ok)
title	dataset secondary headers
legend	the map legend displayed under the map - may contain html
landmask	supply landmask=Y to toggle land mask on (where available); default is off
map	name of display basemap if desired, otherwise will default to best fit
dilate	choose csq depiction method for readability. Normally, very small squares are dilated for readability, also small gap left between adjacent large squares for same reason. Sending dilate=N will turn this feature off
enlarge	'Y' if requesting larger map when available as specified in the Map_Index file. Large maps are identified by the base image name ending in '-big.gif'
decomp	decompression of strings containing '*' (default is Y, supplying decomp=N will result in faster operation and is useful for debugging but may have some odd visual effects)
redirect	URL for external procedure which will be called if user clicks on an active map
filedesc	name to be appended (before extension) to tmp map file name
inline	if inline=Y, gif image (map) alone will be returned, without surrounding HTML code or interactive form contents
popup	default is a new full size window for redirects. Supply popup=Y for a popup (small) window (can then utilise popH, popW, offsetH and offset W to control window size and positioning)
popH	height of popup windows (pixels) - will use 700 if none specified
popW	width of popup windows (pixels) - will use 800 if none specified
offsetH	offset from top for popup windows (pixels) - will use 50 if none specified
offsetW	offset from left for popup windows (pixels) - will use 50 if none specified
debug	set for debugging diagnostics (debug=true), otherwise default is false
sym	symbol marking c-square: rectangle (default) or circle
*clickable.x	represents longitudinal image (pixel) co-ordinate
*clickable.y	represents latitudinal image (pixel) co-ordinate
**factor	scale associated with each map (pixels per degree)
**N_ext	northern extent of image (decimal degrees)
**W_ext	western extent of image (decimal degrees)
bold	Controls boldness of square rendering, for world base maps (and globe views based upon these). Current values employed are 6 (designated "bold", = default), 3 ("intermediate"), and 1 ("finest"). These values refer to the width in pixels that the square boundary is drawn on the original (7200 pixel wide) base map, before re-scaling to produce the size actually viewed by the user. "Bold" squares are also enlarged beyond their actual square boundaries to improve visibility when zoomed fully out.

The c-squares active map tester is a new web interface allowing user-defined input to many of these parameters for demonstration and testing purposes, with additional explanation on these features as required.