Syntax
Note: This is experimental syntax, and it's subject to change if anyone has a better idea. In particular, having the root element be named something other than svg might be a good idea.
Annoshape is intended for use as a URL parameter, so it uses a different syntax than SVG markup; the syntax is inspired by CSS and WKT. However, all the essential aspects of the language (e.g., element names, attribute names and values, property names and values) remain the same.
Permitted SVG elements in Annoshape are line, rect, circle, ellipse, polyline, polygon, and path. (In SVG 2, this list may include the point element and the star element.) Currently, a point can be represented by a circle element, with a radius of 0 or more (which may be used to represent a measure of precision, accuracy, or scope).
Each element is simply the name of the element as a string (e.g., polyline), followed by an optional set of CSS properties contained in parentheses (e.g., (stroke:red;)), followed by the geometry attributes contained in curly brackets with comma-separated values (e.g., {300,131.5,207,174.5,261,290.5,411,220.5,432,265.5,417,272.5}).
For example:
polyline(stroke:red;){300,131.5,207,174.5,261,290.5,411,220.5,432,265.5,417,272.5}
For elements with multiple geometry attributes, such as line, rect, circle, and ellipse, the attributes are separated by a semicolon, with attribute names and values separated by a colon; for example
circle{cx:368;cy:181;r:18}
As with element names, these attribute names are identical to their use in normal SVG markup.
For elements with a single geometry attribute, such as polyline, polygon, and path, the attribute name and/or trailing colon can optionally be omitted; for example, all of these are valid and identical:
polygon{points:351,319,355,317,357,320,361,318,360,314.5,365,312,371,323.5,366,326,363.5,322.5,359.5,324.5,361,328,357,330;}
polygon{points:351,319,355,317,357,320,361,318,360,314.5,365,312,371,323.5,366,326,363.5,322.5,359.5,324.5,361,328,357,330}
polygon{351,319,355,317,357,320,361,318,360,314.5,365,312,371,323.5,366,326,363.5,322.5,359.5,324.5,361,328,357,330}
All numerical geometric values must be unitless (which may be thought of as pixels, but which is actually relative portions of the declared SVG viewbox). Percentages must not be used, and are not needed; the geometry is meant to indicate a fixed area, not a percentage of the viewport, and the SVG viewbox scales the overlay to meet the appropriate size and dimensions of the target image.
As with normal SVG, all elements that apply to a specific image are contained by the SVG root; in the case of Annoshape, this follows the same convention of the name of the element as a string (i.e., svg), followed by an optional set of CSS properties contained in parentheses (e.g., (stroke:red;)). There is no space or other delimiter between the end of one element declaration and the start of another. The whole string is treated as a single URL parameter.
For example:
svg(){circle{cx:368;cy:181;r:18}rect{x:10;y:15;width:42;height:23}}
Each Annoshape string is treated as a single URL parameter, and the initial Annoshape string should be prefixed with the query delimiter ? or the hash delimiter #. Each Annoshape declaration can target a specific image or video resource via Annoshape-specific target-selector property, and multiple image resources on the same page can be targeted by having multiple Annoshape declarations delimited by the ampersand &. The value of the target-selector property must be a valid selector string as described in the Selectors API specification (e.g. it may be an id, a classname, an element name, etc.); note that the selector string must be properly URL-encoded (e.g., for an id, the # should be percent-encoded as %23). For example:
?svg(target-selector:%23map;){circle{cx:368;cy:181;r:18}}&svg(target-selector:%23house;){rect{x:10;y:15;width:42;height:23}}
Although multiple elements are allowed within a single Annoshape declaration, only one Annoshape declaration must be applied to a single target resource; if more than one Annoshape declaration in a single URL targets the same resource, the final Annoshape declaration must replace all previous Annoshape declarations for that same resource. Note that the same image may be loaded onto a page with multiple img elements; these must be considered separate resources. (The single-declaration restriction may be lifted for timed media where the Annoshape root contains a specific time range; in this case, only one Annoshape declaration per time range may be applied.) (Note: This is how it's currently implemented, but maybe it's a bad idea...? Maybe if an additional declaration is made, all of the declaration can apply. That might not be the end of the world, though it would mean that multiple SVGs would stack and that might hurt performance.)
If a URL of a loaded page is changed to remove any Annoshape declaration, that Annoshape instances on all target resources on that page must be removed.
URL Fragments versus URL Queries
An Annoshape declaration can be used as either a URL fragment (or “hash”), or as a URL query, depending on the content type that it's targeting. There is no syntactic difference between an Annoshape fragment or query, other than the initial delimiter.
A fragment should be used if the target resource is loaded with no extra information needed, such as a static image. An Annoshape fragment must be declared after the end of any query string, and must begin with a hash symbol (#), like so:
#svg(target-selector:%23house;){rect{x:10;y:15;width:42;height:23}}
Unlike typical fragment strings, which consist solely of the id of the target element, an Annoshape fragment declaration can include multiple targets; an Annoshape fragment string must begin with a hash symbol (#), and must be composed of one or more Annoshape declarations separated by an ampersand (&), like so:
#svg(target-selector:%23image1;){circle{cx:368;cy:181;r:18}}
&svg(target-selector:%23image2;){rect{x:10;y:15;width:42;height:23}}
Because a URL can have only one fragment string, a URL with an Annoshape fragment string cannot also have a fragment identifier to scroll the target element into view, which would be inconvenient; therefore, the target element of the first Annoshape declaration in fragment string must be scrolled into view.
A query string should be used if the target resource needs extra information to be properly delivered by the server, such as a particular tile, section, or projection of a map, or a specific time range for a streamed video. Note that it is a common convention for a query string to be comprised of both a name and a value (known as a “name-value pair”), or often several name-value pairs separated by an ampersand (&), but this is not mandatory syntax, and Annoshape does not follow this convention; instead, an Annoshape query string must begin with a question mark (?), must be composed of one or more Annoshape declarations separated by an ampersand (&), like so:
?svg(target-selector:%23map1;){circle{cx:368;cy:181;r:18}}
&svg(target-selector:%23map2;){rect{x:10;y:15;width:42;height:23}}
Both a query string and a fragment can be used, such as when multiple resources are being targeted, as below:
http://example.com/for-sale.html
?svg(target-selector:%23map;){circle{cx:368;cy:181;r:18}}
#svg(target-selector:%23house;){rect{x:10;y:15;width:42;height:23}}
Note that only the single-declaration restriction also applies to Annoshape declarations that target the same resource via a query string and a fragment string in the same URL.
Default Styles
The default style for all shapes in Annoshape is different than regular SVG. The style defaults are fill:none, stroke:black, and stroke-width:3px. All of these style can be overridden, and additional styles can be applied; some style properties are particularly useful for delineating overlay shapes, such as opacity, stroke-linecap, stroke-linejoin, and stroke-dasharray. Markers are also useful, but more complicated.
Geographic Information Extensions
For use with mapping, rather than simple images, several more pieces of information are needed in order to establish the proper context for the shapes within the coordinate system of their root SVG canvas. For example, a link to a map webapp needs to indicate to the map which zoom and pan states are needed to properly apply the Annoshape overlay. In addition, because the map is in its own Coordinate Reference System (CRS), with its own horizontal and vertical bounds (expressed as X-min, X-max, Y-min, and Y-max), and possibly with its own projection, all these details need to be supplied in order to properly overlay the SVG shapes, lines, and points to express the original intent.
In the disciplines of Geographic Information Systems (GIS) and geodesy, a Coordinate Reference System (CRS) –also known as a Spatial Reference System (SRS)– is a codified framework to specify any given location on Earth by a set of three numbers (coordinates) describing the latitude, the longitude, and optionally the altitude; each CRS defines this framework in a different way, with different reference points. There are two types of CRS: Geographic Coordinate Systems (GCS); and projected coordinate systems. One of the most common GCSes is WGS84 (World Geodetic System 1984), which is a coordinate system that defines an angular unit of measure, a prime meridian, and a datum; the datum defines an ellipsoid that describes the idealized shape of the Earth and the relationship of the ellipsoid to the Earth itself; together, all of these components allow us to describe a global location with functional precision. Even with this information, however, features of a map may look distorted because the surface of the Earth is a spheroid, not a plane; thus, a view of a map also includes a “projection”, or a systematic transformation of the raw latitude and longitude coordinates onto an appropriate mathematical surface, is used. No map projection is “true” –each is a distortion of the coordinate data– but different projections are good for different tasks, such as measuring distance, area, shape, direction or bearing, scale, and so on, and the selection of a projection may depend on its suitability for different scales, whether the area has a larger east-west extent or north-south extent, or the latitude and longitude of the region.
Each projection explicitly operates within the context of a CRS, and the concept of a CRS incorporates both the Geographic Coordinate System (like WSG84 or NAD83) and the projection (like EPSG-2264). Each CRS has a unique code with the EPSG registry (maintained by OGP, the International Association of Oil and Gas Producers), which describes its applicable region, units of measure, underlying CRS for projections, reference latitude and longitude, and many other parameters that allow for its transformation into another CRS.
No single map, projection, or GCS is best for all purposes, and many different systems are in place around the world, each with many different datasets that use that CRS. Thus, a robust system for mapping should include the ability to adapt to any of these geodetic localizations, and to use the data that is available. To that end, Annoshape does not define a single canonical CRS, but relies on its own geometric (not geographic) coordinate system and established dimensions and viewbox, and provides a set of properties that allow that coordinate system to be transformed into the CRS that was used to create the original overlay graphics (and from there, potentially transformed into any other desired CRS).
Annoshape does this by defining 5 GIS-specific properties: gis-x-min, gis-x-max, gis-y-min, gis-y-max, and gis-crs. These properties, while not formal CSS properties, are nevertheless included in the list of parameters in the SVG root, along with its CSS properties, like so:
svg(width:830;height:582;viewbox:0,0,830,582;
gis-x-min:1981140.803;gis-x-max:1989960.339;gis-y-min:783308.997;gis-y-max:789490.642;gis-crs:EPSG-2264;)
{circle{cx:368;cy:181;r:18}}
Unlike CSS properties, these properties are not intended to change the appearance of the SVG in the browser, but rather to inform the underlying mapping system which parameters should be used when fetching the desired map. This is intended as a universal system for marking up web maps (as well as other images).
gis-x-min
The eastern (left) boundary of the described area, in the default units of the GCS, expressed in decimal degrees where applicable.
gis-x-max
The western (right) boundary of the described area, in the default units of the GCS, expressed in decimal degrees where applicable.
gis-y-min
The northern (top) boundary of the described area, in the default units of the GCS, expressed in decimal degrees where applicable.
gis-y-max
The southern (bottom) boundary of the described area, in the default units of the GCS, expressed in decimal degrees where applicable.
gis-crs
The EPSG code for the Coordinate Reference System (CRS) used in the described area, in the format EPSG-number.
Issues
- ISSUE:How to deal with x-min etc. for maps that have been rotated (e.g. where north is in a different direction than the y-min/top)??
- ISSUE:How can we leverage CSS transforms?
