Annotation (single labels)

From gvSIG CE Wiki

Jump to: navigation, search

Annotations (formerly called 'single labels') are labels that the user can place directly in a special annotation layer. The latter is just a simple point geometry shapefile with an additional (initially empty) '.gva' file accompanies the shapefile set.

The extAnnotation extension handles annotation layers. It provides interactive tools as well as special rendering and CAD editing methods for annotation layers.

Annotation layers currently have six standard attribute fields:

  • Text
  • TypeFont
  • StyleFont
  • Color
  • Height
  • Rotate

The first field contains the label text, the remaining fields are for styling. Every annotation can have its own text and styling. There are tools for:

  • Deriving a new annotation layer from an existing layer.
  • Loading an annotation shapefile as annotation layer.
  • Placing new annotations into an annotation layer.
  • Modifying existing annotations in an annotation layer using the CAD editor.

Annotation layers can either be loaded as regular point shapefiles or as annotation layers (using the dedicated tab in the 'Add Layer' wizard). Only in the latter case will the annotation tools be available for the loaded layer.

The current tools are powerful, but documentation is sparse and a lot of improvements are needed to establish a more intuitive workflow.


Clarifications needed

  • How are empty labels in the 'Place annotations' tool handled?
  • What happens if SQL labels with attribute field references are used on the annotation layer itself?
  • Does setting annotation options in program preferences work? [CHECK: It should work: code is present.]
  • Presumably, the ".gva" file stores the annotation layer settings as set on the layer's properties page. Correct?


  • Attribute schema:
    • Standard names for attribute fields must be improved [DONE]:
      • Text = labeltext
      • TypeFont = fonttype
      • StyleFont = fontstyle
      • Color = fontcolor
      • Height = fontsize
      • Rotate = fontrotate
    • When creating new label layers: Use schema above. [DONE]
    • When processing existing label layers: Support both new and legacy schemas. [DONE]
  • Allow user to create an empty annotation layer (place in View->Create Layer As).
  • Implement break-out labels: It should be possible to display annotation at a distance from the actual labeling points and (optionally) draw connection lines (straight, or with angular or rounded connectors); for this we need to add more standard attribute table fields as well as enhance the annotation rendering methods.

Tool: Export as annotation layer

When exporting a layer as annotation layer, the user can choose where the annotation points should be placed in relation to the geometries of the layer.

  • Choice of label location is bogus, since only 'Center' is supported.
  • Choice of label location 'None' does not even allow the user to swith to the next page.
  • Choice of label location should also include 'First' and 'Last' (vertex).

Label placement: Check current algorithm for "center" and implement the following:

  1. Center
    1. Points: Ignore.
    2. Lines: Mean distance along (part) of a line string. One label placed per part. All labels are guaranteed to lie on the line string. [DOES NOT WORK: labels are not placed on lines. Multi-part geoms not tested]
    3. Polygons: Geometric center of outer ring. One label placed per part. If there are holes in the polygon or it is strongly concave, then there is not guarantee that the label will lie in the area of the polygon. [SEEMS TO WORK AS EXPECTED, but multi-part geoms not tested]
  2. First
    1. Points: Ignore.
    2. Lines: First vertex (part of) line. One label placed per part.
    3. Polygons: First vertex (part of) polygon. One label placed per part.
  3. Last
    1. Points: Ignore.
    2. Lines: Last vertex (part of) line. One label placed per part.
    3. Polygons: Last vertex (part of) polygon. One label placed per part.

Note: Label placement algorithm is here: com.iver.cit.gvsig.fmap.core.v02.FLabel.createLabelPoint(Shape).

Tool: Place annotations

This tool allows the user to add new annotations (points) to an existing annotation layer (called the target layer). It is actually quite flexible, because the user can select any number of source vector layers from which to derive label text. The text can be simple string literals, numeric expressions or even SLD grammar expression (same as the advanced labelling engine uses). If the user then clicks on any feature in the currently active layer/s (a small tolerance threshold is applied), the label text will be generated at that point and a new annotation point added to the target layer. If the target layer is used as source layer, then there will be no check if there is a feature under the cursor. Instead, the new label is placed exactly where the user clicked.

  • Logics for enabling this tool must be improved:
    • Enable only if (1) exactly one annotation layer is currently active and (2) that layer is not in editing mode.
    • Tool toggling does not work correctly. Perhaps this should not be a toogleable tool?
  • Main UI improvements:
    • Automatically set active annotation layer as target disable choice of target layer in UI.
    • Change window title to display name of target layer.
    • Add a 'Done' button.
    • When switching to another tool (e.g. 'Pan'), the annotation tool gets lost and cannot be restored from the UI. So we need a button to start the annotation placement tool from the main UI.
  • Setting up source layers UI:
    • Use the word "source(s)" in the dialog.
    • Remove the bold layer: prefix that is displayed in front of every source layer.
    • For very large TOCs, we might want to restrict the number of sources for labels.
  • Others:
    • We probably need to make sure that only literal label expressions can be used as label text for the target layer.
    • Warn if an/the active source layer's label expression is empty and the user tries to place a label.

Tool: Modify annotations

This tool is available when an annotation layer is put into editing mode. In addition, the CAD tool for moving points is replaced with a tool that draws a bounding box around the annotation point. The four corners of the latter can be moved individually to define position, height and baseline (rotation) of the label. This is flexible but cumbersome if the user only wants to move the point's positition. Therefore:

  • Add a button and a text field to the tool UI to pick or enter a new annotation point coordinate.


  • NumberFormatException is thrown when a very long integer is entered as label text for a layer.
  • Some of these may still apply:
  • There is bad interaction between annotation layers in the View and in a Map layout:
  • When adding an annotation layer via "Add Layer"->"Annotation", the ".shp" extension is copied into the TOC layer name.
  • Selections in annotation layers are not marked with the selection color.
  • Export layer as Annotation Layer: Choosing label mode "Center" produces only one point in the center of the layer's entire dataset; label mode "none" produces the expected result, i.e. one label per feature.