Map Annotation

Please read Terms and conditions, Copyright, Fair Use, etc. if you are going to use the facilities described here.

Introduction

This page provides information about interactive annotation of the University Map.

If all you want to do is create a link to show your department etc on the map, you don't need to create any annotation. Just use the link shown in your browser address bar when you are looking at the full results for the institution. For example: https://map.cam.ac.uk/Department+of+Geography . This also means if you move, the link will show up-to-date information without any changes.

Also if you only want to put some pins on the map, you can do this directly from the map: click where you want them and choose the pin icon (draw marker). Then copy the URL from the browser address bar.

If you are interested in scripting or programming overlays from other data sets, see the UCamGeoJSON API.

This page deals with more substantial annotations, produced interactively.

Why?

It is useful to be able to customize the University Map. This might be for

• something ephemeral, like emailing directions or highlighting a meeting place to someone;
• something semi-permanent such as locations of a series of events around the University (for example, consider the Cambridge Shakespeare Festival, or Science Week);
• something permanent, such as more detail or special interest information (for example, consider disability information, college staircase locations, college meeting rooms, or the Granta Backbone Network).

Where?

This is achieved by referencing in the map URL a set of annotations stored at a another https URL somewhere on the internet. This could be

• storage provided by the map server itself (University login required),
• your personal University web pages,
• a departmental website,
• a shared Dropbox file (or other cloud service)
• anywhere, really, subject to certain security limitations

This URL is given in the fragment part of the map URL, that is, the bit after a hash sign '#', like this

 https://map.cam.ac.uk/#http://some.annotations.com/annotation1.json

How?

The link provides a set of data in UCamGeoJSON format. This can be generated programatically where you have a geographically-minded data set to display, but for more casual use interactive Map Annotation, in effect to draw on top of the map and then save your annotations for other people to refer to.

Getting started

Annotate the map on the More link of the main map takes you to the map annotation page. This provides a web app where you can draw onto the map and then save the drawing for other people to see, by providing a link on a web page or sending them a link by email, and so on.

A set of annotations comprises one or more features, which are independent from each other, and layered so that if they overlap one will draw on top of another. You can draw three different kinds of feature: points (to which images and text can be attached), lines and areas.

Points represent real geographical locations, so as you zoom out they get close together visually. However, images and text applied to a point are fixed size: they do not scale up and down as the map is scaled, so they may overlap at larger scales.

Adding points, lines and areas

If you make a mistake at any time, you can use the Undo button (or the CTRL+Z key) to reverse your change. Redo on the Data menu reverses Undo.

Click on the map to make a point. This is shown with a small green or red mark called a handle.

A red handle indicates that it is selected, that is, identifying a point and feature to which changes will be made. The others are green. Select a handle by clicking on it. Clicking on the already selected handle will deselect it. SHIFT+Click (that is, click while holding down the Shift key) selects additional handles. You can also select (the first handle of) all features using Select All and de-select everything with Select None on the Features menu.

Having made a point, you can now either can add a second point to start drawing a line, or apply text and/or an image to the single point.

To help you see where a line will go, a putative 'rubber band' line is connected from the selected point. This will go away if you add an image or text, but if it bothers you, press the ESC key or press the button provided to explicitly turn off line formation.

Once a single point is selected (which it will be immediately after you have made one), the left hand side panel changes to offer a form where you can add images, text, colour, borders etc. to the point. Details below.

If instead you make a line, the panel changes to offer properties for the line, such as width and colour. Click again to add further points to the line. You can extend an existing line from either end by clicking the relevant handle.

Once you have at least three vertices, you can form a closed area by clicking on the first handle. If you cancel the rubber-band line with ESC, clicking the first handle will just select it, and therefore offer to extend it from the other end.

Changing existing features

Move a point by dragging its handle. You can either re-position a decorated single point, or change the shape of a line or area by moving one of its vertices.

You can also move the whole of a line or area by CTRL+dragging any of its handles (that is hold down the Control key while clicking on and dragging).

The menus provide means to change existing features. Naturally, the Features menu offers things you can do to features as a whole, and the Points menu things you can do to points.

Features

• Delete feature deletes all the features containing selected points.

• Bring to front and Send to back change the order of features containing selected points in the layers, affecting how they appear when they overlap (and also which feature you would be able to drag around to move it: if features overlap, the one on top will be the one that is moved).

• Duplicate feature to make a copy of the features containing selected points, slightly offset from the originals

• To start over with no features, use Clear all on the Data menu. (If you accidentally delete everything with this, you can Undo it).

• Select all selects the first handle of all features.

• Select none deselects all selected handles.

Points

• Insert point adds a new point half way along the line segment of a line or edge of an area which precedes the selected point. Once you have inserted a point, you can move it to where you want it by dragging in the usual way.

You may well have forgotten which way round the points go. Notice the point before the selected point is a lighter shade of green. The new point goes between the selected point and the lighter green point.

• Remove point removes the selected point. If this would reduce an area to fewer than three vertices, it will turn into a line, a line with two vertices originally will become a point, and a point will disappear as it would with Delete Feature.

• Make horizontal and Make vertical align the selected vertex with the previous (lighter green) point horizontally or vertically respectively.

Saving and Loading

Save features

When you have completed your annotation, you'll want to do something with it. Use Save features on the Data menu to do this.

There are two ways you can save your data:

• Store it on the map's server (University login required). Data saved in this way can be updated from the same account in the future without the link changing.

• Take your own copy and place it on your own server. You can either save to a file or copy the data (it is just a text file) and paste it where needed.

If you are making a link to the annotated map to go on a web page, then you would store the file as you would an image in your web site and reference it as above in the map URL.

Saving in the cloud

Users who don't have or want personal web space, can use widely available cloud file storage services - but only those which can expose files both

• through a public, unprotected link, and
• directly, that is without an inherent user interaction such as the link directing users to a page from which they can then download the file

Dropbox can do this. Once you have put your file into Dropbox (the process is much the same as University web space described above), ask to share your file, and choose the Share Link option. This is a download page, not the file itself. If you append ?raw=1 (or replace ?dl=...) to their URL, you will be able to access the file contents directly (rather than the dropbox preview page for the file). However, the map already knows this, so it will substitute the direct URL automatically if you do not.

A note about protecting annotation overlays

Most overlays will be accessible by anyone who knows the link, and they will work just fine.

However, if you want to make overlays available only to a limited group of people, you need to know a little more.

A web page (such as the map) is not allowed to access data from another website without that site's explicit permission. If you are setting up a web site to serve annotations to the map, you should grant this permission using CORS.

However, most cloud services (where you don't have the option of doing this yourself), including both the University personal web space and Dropbox, do not do this at the server end. Also Internet Explorer version 8 or earlier does not support it at the browser end. So, if it can't get permission directly, the map works around this by asking for the data via its server rather than directly from the browser. Using CORS avoids this step, so is faster where it can be supported.

If you are requiring a University login (or some other login service) to access the data (in order to restrict overlays only to either all University account holders, or a select group of people - for which you will need to know how to access Lookup groups via LDAP, or have implemented your own scheme), then accessing the data via the map's server will not work, because the server isn't logged in as you, only the browser. This means that for this kind of access, the browser must be able to access the file directly, so

• you must implement provision of CORS headers with the overlays you serve
• the Access-Control-Allow-Origin header may not use a wildcard for the permitted site: it must specify https://map.cam.ac.uk explicitly.
• you must also use the header 'Access-Control-Allow-Credentials: true' so your users' login cookies are delivered to your site and it can therefore see they are logged in.
• nevertheless, Internet Explorer versions 7 and 8 users will not be able to access the overlay because their browser does not implement CORS. Your protected user group must use more modern browsers.

Load features

Load features on the Data menu does the opposite of Save. You can load annotations from a URL or by pasting the contents of a file, and then amend them.

If you load data originally saved permanently to the map server using your University login and the identifier provided, then when you come to save again, you will be offered the opportunity to replace the original data using the same link (as well as the other options).

If the map URL indicates annotation when you start annotating, that annotation will be loaded so that it can be amended.

Note that you cannot load data directly from a login protected area. As you were presumably responsible for putting it there in the first place, you know how to get at the file and paste its contents into the Load Features box, and then download the amendments locally to replace the file in the same way.

Changing Appearance

Put appropriate numbers in the boxes and use the menus etc in the left hand panel to change the appearance of the feature or features you have selected.

Click the subheadings in each section to set properties in that group.

Most sizes are measured in pixels (dots on the screen). There is a pixel scale for reference at the bottom of the left hand panel.

Heading

With nothing selected (deselect any selected point by clicking on it) you can set a heading for the whole page. The recipients of your annotations will see this in the same style as the headline in the left hand panel as shown while annotating.

Further information can also be displayed beneath the heading by entering it in the box. Any web page URL included in the text will be made live (that is, can be clicked so the user is taken to the URL). One or more consecutive new lines in the text starts a new paragraph.

By ticking the Markdown box beneath, your information can be more richly formatted to including images, links, lists and so on. The text in the box is then interpreted as Markdown, which is a widely-used, simple and quite readable text markup language. For example, putting underscores around a phrase italicises it. Here's the documentation. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at dillinger.io. (Markdown can also be used in pop-up bubbles displayed when clicking on a point).

Point style

The image and text that can be shown at a point are surrounded by a box. That box can have a coloured background and/or border. The relationship of the text and image position and size of the box can be adjusted, and the box can be positioned relative to the point (so that a particular place in the icon - an arrow head for example - can lie on the point).

Image/Icon

You can choose from some ready-made symbols (including arrows at 5 degree intervals), or use an image somewhere else on the internet, including one you put there yourself, so long as it has a URL and is served over https. The image will usually be in a JPG or PNG file. PNG is preferable for icons and symbols as they can have transparent backgrounds - for example a pointing hand symbol. JPG is better for general pictures - for example, a photograph of you marking the location of your office.

Many browsers let you pick up the URL of an image by right clicking and then 'Save Image URL' or similar. Beware of using third-party images, both for copyright reasons and longevity you may have no control over.

You can adjust the image to be smaller than the original. Set just one of width and height to maintain aspect ratio. This is independent of the width of the enclosing box, except that if you don't set the box size explicitly, or add text, it will be the same size as the image.

You will often want to centre or otherwise adjust the position of the image relative to the point, in Layout.

Text

Type some text to be displayed. Unless you have chosen a ready-made image as well, or manually adjusted the offset, the box containing the text will extend to the right and down from the point. You may want to restrict the width, but not the height, of longer text.

You can also adjust the font, size, colour, style, underlining and various spacings from this panel.

Layout

These settings control how the box, image and text are positioned in relation to each other.

The offset of the top-left corner of the box will often be negative to move the box up and to the left.

Link, Hover & Pop-up

You can add a link to the box so that your recipients can be taken to a particular web page when they click on your annotation. Enter the URL of your target page here. Note that the links aren't actually active while drawing annotation because it is too easy to accidentally click on one and move away from annotating the map.

Also, you can provide text which appears when the mouse hovers over the annotation. On most tablets, this requires a tap to see, and if there is also a link, following the link then requires a second tap.

Thirdly, you can put further information in a pop-up, like a "speech bubble", which appears when the user clicks on your annotation. Like the hover text, this can also be just some plain text. However, if you tick the Markdown box, the content can be richly formatted, including images, links, lists, bold and italic, text colouring etc. This is done using markdown, a widely-used, simple and easy to read text markup language. Here's the documentation. If you want a bit more space and feedback to prepare your rich text, there's a neat Markdown editor at dillinger.io.

Background

Choose the colour of the background of the box here, and whether it is partially transparent.

Padding is an extra coloured margin around the box. Even if the box is transparent, the border still takes this into account, and so the location of the top-left corner of the box is positioned relative to the point.

Without any padding, text or border, an opaque image will occupy the whole box so you won't see the background colour.

Border

You can give a width, colour and radius for rounded corners here. A subtle 1 pixel dark border with rounded corners is often helpful to delineate the annotation against the map background.

Line style

Colour and width

Set the colour and width of your line here - if you don't change it, it will be a thin (1 pixel wide) solid line.

Note that lines are drawn with rounded ends and corners. This is more noticeable with thicker lines.

Details

Your line can be partially transparent. You can also use dashes.

Area style

Fill

Set just the colour and transparency of the filled area here.

Outline

Set the width and colour of the outline around the area here, and how transparent it should be. You can also have dashed outlines.

Note that the outline is drawn centred on the line around the area. As well as intruding into the area, partially transparent thick outlines are transparent with respect to the area as well as the map.

Templates

Template annotations are ready made items which can be used to get a head start in preparing an overlay.

Typically you would

• go to Annotate the Map,
• select Data > Load Features,
• enter the template URL to bring the set of shapes defined by the template into your map
• move them and modify them to suit your needs.

Pointers and labels

 https://annotate.map.cam.ac.uk/templates/pointers.json

This template makes up to 99 numbered shapes (as images) in a variety of sizes, styles, colours, pointer orientations and resolutions, according to the query string in the URL.

For example
  https://annotate.map.cam.ac.uk/templates/pointers.json?size=30
produces shapes 30 pixels across;
  https://annotate.map.cam.ac.uk/templates/pointers.json?size=30&colour=blue
additionally colours them blue.

If you load this annotation it will position the requested markers in a neat grid over the centre of town, which you can then move to your desired locations.

Query string options are as follows:

   start=N       - N is first label number (1..99, default=1)
   end=N         - N is last label number (1..99, >= start, default=25)
   size=N        - N is width in pixels of the displayed pointer (heights depend on icon, 
                   but are usually more, default=25. This is not necessarily the same as 
                   the actual number of pixels in the image, which can be varied with 
                   resolution below, just the size it is displayed at).
   resolution=R  - R in dots per inch, 72..300, default is a nominal screen resolution (a little 
                   over 90dpi) such that the size is the number of pixels both of the display and the image
   colour=C      - C is colour of the pointer background, a CSS colour (name, #NNNNNN - with or without
                   the hash, but requires URL encoding if included, or rgb(r,g,b)); default=tomato
   color=C       - same as colour
   textcolour=C  - C is colour of the text (default=white)
   textcolor=C   - same as textcolour
   shape=S       - S is one of: roundel, plantpotrounded, plantpotsquare, droplet, arrowhead; 
                   default=plantpotrounded
   direction=D   - D is one of the eight compass points indicating (where relevant) which direction the 
                   pointer should face, i.e. S, SE, E, NE, N, NW, W, SW; default=S

Bear in mind some of the more complicated options (especially for colour) will require URL encoding (it's probably easier to omit the hash in a CSS colour for this reason). If that causes difficultioes, you can always open the URL directly, copy the JSON output from your browser, and paste it into the Data > Load Annotation box instead of the URL.