Tutorial - Annotations

Draw different annotations, optionally setting the aspect ratio or a fixed size for rectangles and ellipses.

Define some HTML with the divs for the map and controls.

Step 1

Active

Inactive

Define some CSS to position the controls at the top of the window.

Step 2

Active

Inactive

Create a map, center it in an interesting area, and create an annotation layer. The annotation layer specifies clickToEdit which allows clicking on an existing annotation to modify it.

Step 3

Active

Inactive

When the you click the Draw button, if it is not currently selected, switch to drawing the currently selected annotation style. If already drawing an annotation, cancel the drawing.

For rectangles and ellipses, use the aspect ratio input field to constrain the aspect ratio. Numbers greater than 1 will be wider than tall; numbers between 0 and 1 will be taller than wide. You can enter a comma-separated list of aspect ratios to snap to the closest value.

Step 4

Active

Inactive

Rectangles and ellipses can also be constrained to a fixed size rather than an aspect ratio, using the "Fixed Size" field. square and circle always use a fixed aspect ratio of 1 and cannot be given a fixed size, so the field only applies to rectangle and ellipse.

Unlike an aspect-ratio constraint, a fixed-size shape has no remaining degree of freedom to resize as you drag - it is always exactly the size you specify. Because of this, dragging moves the shape instead of resizing it: the rectangle stays centered on the current mouse position, so it translates smoothly with the cursor.

$('#draw').on('click', () => {
  if ($('#draw').hasClass('drawing')) {
    // turn off drawing an annotation
    annotLayer.mode(null);
    $('#draw').removeClass('drawing');
  } else {
    // mode is the type of anntoation to draw
    var mode = $('#mode option:selected').attr('id');
    var opts = {};
    if (mode === 'rectangle' || mode === 'ellipse') {
      // if specified, a fixed width and height (comma-separated) take
      // precedence over the aspect ratio
      var fixedsize = $('#fixedsize').val().trim();
      if (fixedsize) {
        var size = fixedsize.split(',').map((v) => parseFloat(v));
        opts.constraint = {width: size[0], height: size.length > 1 ? size[1] : size[0]};
      } else {
        // otherwise, if specified, set the aspect ratio constraint to a
        // list of values
        var aspect = $('#aspect').val().trim();
        if (aspect) {
          opts.constraint = aspect.split(',').map((v) => parseFloat(v));
        }
      }
    }
    // switch to drawing mode
    annotLayer.mode(mode, undefined, opts);
    $('#draw').addClass('drawing');
    // when finished, turn off the button style so it is obvious
    annotLayer.geoOnce(geo.event.annotation.mode, () => {
      $('#draw').removeClass('drawing');
    });
  }
});

Step 5

Active

Inactive