Add MoEML Locations to the Agas Map

Introduction to the Agas Map

Our implementation of the Agas Map is based on the OpenLayers 4.6 library and presents the map as a tiled image at a range of different resolutions.1 Locations are plotted on the map in three forms: Each of these forms serve a different purpose, depending on the type of location you are encoding; each of these shapes and their purposes are discussed in more detail below.
The information used to display locations is provided to the map through two JSON files:
  • categories.json: provides information about all the location categories in our document type taxonomy
  • agasLocations.json: provides information about the locations, including each location’s document type(s) and the list of referring documents
These files are created during the static build process and are generated from the metadata contained within the TEI location files.
The Agas Map interface can also be used to create new shapes, lines, and points for locations, which can be either associated with a location file or can be used more generally to interact and draw on the map. This document will explain how to do both.

Creating a Polygon

To create a polygon shape, first zoom right into the map so that the shape you want to outline is taking up most of the window. In this example, we’re going to outline St. Mary Woolchurch:
agas_draw_poly_01.png
Then choose Polygon from the Draw a shape drop-down list:
agas_draw_poly_02.png
A red box appears at the bottom of the screen. We’ll see the purpose of this later. You’ll notice that the cursor turns to a blue point. Now you can click on one of the corners of the object to add a point. Move your mouse to the next corner, and click there to add the next point:
agas_draw_poly_03.png
Keep adding points until you have outlined the whole object:
agas_draw_poly_04.png
Click back on the original starting point to complete the shape.
agas_draw_poly_05.png
Two things will happen: the shape will change colour to show that is is complete, and in the red box, a block of XML code will appear. This is the TEI <surface> element that you need to add into the location file for the place. In Oxygen, open up the appropriate location file (in this case, STMA37.xml), and locate the <facsimile> element. Note that if you are creating a new document or adding a location to an existing document that is not already on the Agas map, it may not contain a <facsimile> element. In this case, simply add a <facsimile> element between the <teiHeader> element and the <text> element. However, you may find that there is already a <surface> element from the old Agas map images. Leave this alone, but add the new element immediately after it:
agas_draw_poly_07.png
You’ll notice that this is invalid when we first paste it in, because the location id is wrong. Change the first part of the @xml:id attribute on the <zone> element to match the location’s @xml:id:
agas_draw_poly_08.png
What if your shape is not perfect first time around? You can easily edit it after it’s completed. Put your mouse over one of the existing points to click and move it; put your mouse over one of the lines to add a new point. Every time you make a change to the shape, the XML in the red box will update itself automatically.
agas_draw_poly_06.png
If you need to delete one of the nodes in your shape, press the Shift key and click on it.
It is best to have the map zoomed to its maximum size when you create the shape, because you’ll be more accurate. If you’re outlining a large area, this may mean that the shape does not completely fit on the screen. Don’t worry about this; even while you’re in the middle of drawing the shape, you can still click and hold (hold down the mouse button), drag the map around, and release without adding a new point in your shape. It’s only when you click and release immediately that a new point is added.

Creating MultiLineStrings

While we usually draw buildings as shapes, streets are drawn as MultiLineStrings (in other words, a series of connected lines). The process is exactly the same as for Polygons, except that to finish the shape, you just double-click on the last point. When tracing a street, start the line in the middle of the junction where the street starts, and end in the middle of the junction where it ends. Keep the line in the middle of the street.
agas_draw_street.png

Creating Points

Some locations cannot be precisely outlined, perhaps because although we know approximately where they were, they do not actually appear on the map. You can use a Point for this.
Creating a Point is the simplest process of all: select Point from the drop-down list, then click on the location.

Creating a MultiPolygon

There will be some circumstances in which you need to associate multiple polygons with a single location. For example, imagine that a guild owns two buildings which are not contiguous; in one sense, they are the same location, but they are clearly two separate shapes on the map.
This can be done by creating multiple <zone> elements inside the <surface> element for the map. Here is an example:
<surface>
  <graphic url="agas_full.jpg"/>
  <zone xml:id="STBO4_1_agas" points="18913,6593 18919,6692 18983,6687 18994,6686 18995,6621 18995,6593 18913,6593"></zone>
  <zone xml:id="STBO4_2_agas" points="18994,6681 18998,6708 19007,6721 19032,6721 19033,6682 18994,6681"></zone>
</surface>
Each <zone> has a different @xml:id, created by adding an underscore followed by a digit after the main location @xml:id. You will have to draw each of these shapes separately on the map, selecting Polygon from the drop-down list; create the first one in the normal way, copying the whole <surface> element into the location file, and then for each subsequent polygon, copy only the <zone> element from the code box into the appropriate place as a sibling of the first one.
Note that you can only combine polygons in this way; you cannot create sets of MultiLineStrings or Points.

Editing an Existing Location

Sometimes you will have to make changes to a location which has been entered by someone else, and is already showing on the map. To do this, first zoom into the location and select it:
agas_edit_shape_01.png
Then choose Clone selected feature from the drop-down list. The shape will turn into a red outline which you can edit as explained above. As you edit, the XML in the red box will change, and when you’re happy with the result, you can copy/paste the XML into the location file, replacing the original <surface> element. Ensure that you update the <respStmt> in the <teiHeader>, giving yourself credit as the Geographic Information Specialist. See Create a MoEML <teiHeader> for details on how to encode a <respStmt>.

Bookmarking Shapes

Just as you can bookmark locations or sets of locations, you can also bookmark a shape you have created. This can be handy if you’re emailing someone and would like to refer to a specific location on the map, if you would like to suggest a particular location for inclusion, or if you would like to share a custom shape that does not belong in the database.2 To do this, simply create the shape as you normally would, and then when you’ve finished, press the Bookmark button. A long, inscrutable URL will be created and a popup alert will tell you that it is about to redirect you to the bookmarked URL.
agas_bookmark_alert.png
Press OK and the page will redirect you to the bookmark URL. Once the page has reloaded, you can copy and paste the entire URL in the address bar. If you plug this URL into a browser, the map will recreate the shape and zoom to it, also showing the TEI <surface> element at the bottom of the screen.

Uncertainty and Imprecision

It is often the case that a feature may not appear on the Agas Map, although we know more or less where it should be if it did appear; or that we know more or less, but not exactly, where a feature is. In order to be truthful, we need to record the level of certainty and precision associated with a location. The <certainty> and <precision> elements enable us to do that. We use <certainty> to quantify our confidence that the location assigned is the correct location; and we use <precision> to quantify how accurate our point or outline is assumed to be. This is perhaps best explained through examples.
<zone xml:id="ROSE66_agas" points="14676,9076 14910,9081 14918,9405 14684,9401 14676,9076">
  <precision precision="low" resp="mol:HOLM3"></precision>
  <certainty cert="medium" resp="mol:HOLM3" locus="value"></certainty>
</zone>
The <precision> and <certainty> elements appear as children of the <zone> element to which they refer. In the absence of these elements, certainty and precision are assumed to be high. The @precision and @cert attributes record the level of certainty or precision in each case; allowed values are:
  • "high": default value
  • "medium"
  • "low"
  • "unknown"3
It is always good practice to provide @resp (using the standard "mol" prefix and your @xml:id) to identify someone (usually yourself) as the person responsible for introducing or encoding this expression of doubt. Where appropriate, you might also provide @source to point to one or more sources of evidence; the source can either be an internal bibliographic item (and thus pointed to using the standard mol prefix and the @xml:id of the bibliographic item) or an external URI.
The method outlined above is relatively crude; it allows us to say that the feature may not in fact be at the location specified (<certainty>) and/or that the coordinates provided may be somewhat inaccurate (<precision>). You may wish to add a <note> inside the <zone> to clarify the situation for a human reader, and it is also possible to provide much more specificity in the encoding if we determine that this is desirable. If the location consists of more than one zone, add a <note> inside <surface>.
Note also that using this method, it is possible to encode multiple possible locations for a single feature, each with its own level of certainty; you might believe that it is most likely in one place (@cert="medium") but that it could possibly be somewhere else (@cert="low"), and each location can have its own <zone> element containing a <certainty> element, with @source pointing to the evidence available.
<facsimile>
  <surface>
    <note type="editorial" resp="mol:JENS1">The southern half of the alley, if it existed, would have been destroyed for the building of the Royal Exchange. The northern half ran east of St. Christopher le Stocks. Neither half is visible on the 1633 version of the Agas Map.</note>
    <graphic url="agas_full.jpg"/>
    <zone cert="medium" xml:id="CHRI4_1_agas" ulx="16783" uly="4684" lrx="16883" lry="4817"></zone>
    <zone cert="low" xml:id="CHRI4_2_agas" ulx="16687" uly="4562" lrx="16749" lry="4656"></zone>
  </surface>
</facsimile>

Notes

  1. The OpenLayers implementation of the Agas map was first created in 2014, replacing the old star map. (MDH)
  2. See, for instance, the footnote in Silver Street, which shows the house that Shakespeare may have lived in during his stay on Silver Street. (MDH)
  3. Note that you will almost always encode certainty and precision using "high", "medium", or "low"; there are few instances where "unknown" is useful. (MDH)