Geo Arbores Wiki

Brought to you by: ma15569

Documentation

Authors:

back to [Map Navigator Intro] page

Documentation

* Nodes, Objects and Data Structure

Nodes, Objects and Data Structure

MapNavigator organizes geographic data in a hierarchical tree structure. At the top level, the Root contains one or more LayerNode instances. Each LayerNode represents a logical layer of the project and can contain one or more CategoryNode instances. Categories provide logical subdivisions within a layer and contain ObjectNode instances. Each ObjectNode represents a single geographic object and contains one MapObject, which is the actual cartographic element displayed on the map.

The resulting hierarchy is:

Root
└── LayerNode
    ├── CategoryNode
    │   ├── ObjectNode
    │   │   └── MapObject
    │   └── ...
    └── ...

The Root extends LayerNode and therefore shares its main content-management functionality. CategoryNode also extends LayerNode, while ObjectNode extends AbstractNode and represents the terminal node of the tree.

In the current implementation, the relationship between ObjectNode and MapObject is deliberately one-to-one: each ObjectNode contains exactly one MapObject, and both share the same unique ID.

All nodes have a Name and Description. The Name is used as the label displayed in the project tree. For an ObjectNode, the Name and Description are directly associated with the corresponding MapObject. Consequently, changing an ObjectNode's Name updates both its tree label and the name of the geographic object displayed on the map.

Each MapObject represents an individual geographic feature and contains an ID, Name, Description, AttributeMap, and Style. The AttributeMap stores the attributes associated with the geographic object. LayerNode also has an AttributeMap representing the aggregated attribute structure of the MapObjects belonging to that layer.

The Style defines how a MapObject is displayed. For line features it specifies the line color and stroke; for area features it specifies the area color; and for point features it can define the symbol or image and its rotation. The style also defines the appearance of the label associated with the MapObject's Name, including its font, size, and color.

The overall relationship between organization, data, and visualization can therefore be summarized as:

Root
└── LayerNode
    └── CategoryNode
        └── ObjectNode
            └── MapObject
                ├── ID
                ├── Name
                ├── Description
                ├── AttributeMap
                └── Style

The fundamental principle is that nodes organize and manage geographic objects, MapObjects represent the actual geographic features, AttributeMaps describe their associated data, and Styles define their graphical representation.

Manage Metadata

The Manage Metadata dialog provides a unified interface for managing the main metadata associated with a MapObject or node.

The Metadata interface contains two related but independent functions:

Name and Description — allows the user to edit the actual Name and Description values of the selected object or node.
Property Selection — allows the user to identify existing attribute fields that should be used as the semantic NAME and DESCRIPTION properties.

When enabled, Property Selection is displayed directly below Name and Description within the same Metadata tab.

Metadata
   │
   ├── Name
   │
   ├── Description
   │
   └── Property Selection
          │
          ├── NAME
          └── DESCRIPTION

Name and Description

The Name field contains the name associated with the selected MapObject or node. Changes made while editing the field are immediately reflected in the underlying object.

The Description field contains additional textual information such as notes, comments, explanations, or other descriptive content. It is independent of the Attribute Table unless an attribute is explicitly associated with the semantic DESCRIPTION property.

Both values represent the object's actual metadata and are distinct from the attributes selected through Property Selection.

Property Selection

The Property Selection panel associates existing attribute fields with the semantic NAME and DESCRIPTION properties.

For example, an object's Attribute Table might contain:

ID          125
CITY        Bologna
TYPE        Museum
INFO        Historical museum

The user can associate:

NAME         → CITY
DESCRIPTION  → INFO

The selected attribute does not have to be named NAME or DESCRIPTION. Any suitable existing attribute can be selected.

Available Attributes

The available attributes are obtained from the attributes of the MapObject associated with the current ObjectNode.

The Property Selection panel displays the base names of the attributes rather than their complete internal keys. Duplicate base names are displayed only once, and invalid or empty names are ignored.

NAME and DESCRIPTION Selection

The first selection field identifies the attribute intended to provide the semantic NAME property.

The second selection field identifies the attribute intended to provide the semantic DESCRIPTION property.

When existing semantic assignments are available, the corresponding attributes are selected automatically when the dialog is opened.

If no previous assignment exists, MapNavigator provides a default selection from the available attributes. For DESCRIPTION, the second available attribute is used when possible; if only one attribute exists, it is used for both selections.

These defaults are only initial selections. They do not modify the MapObject.

Selection and Application

An important distinction must be made between selection and property assignment.

Changing a combo box in the Property Selection panel does not immediately modify the MapObject.

The process consists of two separate steps:

User selects attributes
          │
          ▼
Property Selection
          │
          ▼
Selection remains in dialog
          │
          ▼
Manage Metadata / assignment operation
          │
          ▼
Selected attribute keys are assigned
          │
          ▼
MapObject semantic associations updated

The selected indexes can be retrieved from the dialog using the corresponding getNameAttributeIndex() and getDescriptionAttributeIndex() methods. These methods only report the current selections; they do not themselves modify the object.

The actual assignment takes place when the appropriate MapNavigator operation explicitly processes those selections.

This separation allows the user to change or inspect the selections and cancel the operation without unintentionally modifying the existing semantic associations.

Existing Assignments

When the dialog is opened, existing NAME and DESCRIPTION attribute assignments are used to initialize the corresponding selections.

If an existing assignment can no longer be found—for example, because the attribute has been renamed or removed—MapNavigator falls back to the available default selection.

This allows existing associations to be preserved when possible while keeping the dialog usable when the attribute structure has changed.

Relationship with the Attribute Table

The Property Selection panel does not create attributes.

The Attribute Table contains the actual fields and values associated with the MapObject, while Property Selection identifies which of those existing fields should have the semantic roles NAME and DESCRIPTION.

An object may therefore contain many attributes while only two of them are selected for these semantic roles.

For example:

NAME_IT          Bologna
CATEGORY         City
DESCRIPTION_IT   Capital of Emilia-Romagna

The user can select:

NAME         → NAME_IT
DESCRIPTION  → DESCRIPTION_IT

Metadata Tab

When Property Selection is enabled, it remains part of the Metadata tab rather than becoming a separate tab.

The overall properties interface can therefore contain, for example:

[ Metadata ]   [ Style ]   [ Attribute Table ]

with the Metadata tab containing:

Metadata
   │
   ├── Name
   ├── Description
   │
   └── Property Selection
          ├── NAME
          └── DESCRIPTION

This keeps all metadata-related operations together, while Style and Attribute Table remain independent interfaces.

Optional Property Selection

Property Selection is optional.

The NameDescriptionDialog can be created with Property Selection enabled or disabled through its addPropertiesSelection parameter.

When enabled, the additional controls are displayed below Name and Description. When disabled, the Metadata interface contains only the Name and Description fields.

Drawing Mode

Property Selection is not used when NameDescriptionDialog is created for drawing through a DrawMapController.

In drawing mode, the dialog is intended to provide the Name and Description of a newly created object. The values are obtained from and written back to the drawing controller.

Consequently, drawing mode provides only the Name and Description interface and the confirmation controls.

Property Selection is intended for managing the properties of an existing MapObject or node.

Important Distinction

The following three concepts should not be confused.

Name and Description values

These are the actual textual metadata values of the object and can be edited directly through the corresponding fields.

Property Selection

These are the current choices identifying which existing attributes should represent the semantic NAME and DESCRIPTION properties.

Property Assignment

This is the operation that takes the selected attributes and actually stores their corresponding attribute keys as the object's semantic NAME and DESCRIPTION associations.

The Property Selection panel performs the second function. It does not, by itself, perform the third.

Typical Workflow

A typical workflow is:

Select an object in the MapNavigator tree.
Open Manage Metadata.
Edit Name and Description, if necessary.
If Property Selection is available, select the attribute for NAME.
Select the attribute for DESCRIPTION.
Confirm or execute the appropriate operation to apply the selected property assignments.

The result is an object whose ordinary metadata values and semantic attribute associations can be managed from the same Metadata interface.

Attribute Table

The Attribute Table displays the attribute fields and values associated with the selected MapObject. It provides access to the object's descriptive data in addition to its geometric information.

The Attribute Table is available as a separate tab in the object properties interface:

┌─────────────────────────────────────────────┐
│ Properties                                  │
├─────────────────────────────────────────────┤
│ [ Metadata ]  [ Style ]  [ Attribute Table ]│
├─────────────────────────────────────────────┤
│                                             │
│ Attribute              Value                │
│ ─────────────────────────────────────────── │
│ ID                     125                  │
│ CITY                   Bologna              │
│ TYPE                   Museum               │
│ INFO                   Historical museum    │
│                                             │
└─────────────────────────────────────────────┘

Attributes

Attributes are stored as key/value pairs associated with a MapObject. They can contain textual, numeric, Boolean, date, or other supported values.

Attribute keys may internally contain type information or other suffixes. Where appropriate, the user interface displays the corresponding base name rather than the complete internal key.

The Attribute Table represents the actual attribute data stored by the object. It is therefore distinct from the semantic metadata handled by the Metadata tab.

Attribute Table and Metadata

The two interfaces have different purposes:

Attribute Table — displays the actual attribute fields and their values.
Name and Description — manages the object's semantic Name and Description.
Property Selection — identifies existing attributes that can be used as the semantic Name and Description.

For example, an object may contain:

CITY        Bologna
TYPE        Museum
INFO        Historical museum

Property Selection can associate:

NAME         → CITY
DESCRIPTION  → INFO

This does not create duplicate attributes. The Attribute Table continues to contain the original fields and values.

Imported Attributes

Attributes can be imported together with geographic data.

For example:

Shapefile attributes are read from the DBF component.
GeoJSON feature properties are imported as object attributes.
CSV files can contain attribute fields together with geometry, with WKT geometry supported as the final column.

For CSV data, typed attribute names can use suffixes such as _s, _n, _b, and _d to identify supported value types.

A Shapefile is composed of several related files that must remain together:

dataset.shp   → geometry
dataset.shx   → geometry index
dataset.dbf   → attribute table
dataset.prj   → coordinate reference system

Export

When the destination format supports attributes, they can be exported together with the geographic data.

For KML, the object's semantic Name and Description correspond to the KML <name> and <description> elements. Other attributes can be represented as extended data.

Availability

The Attribute Table is provided when the selected object contains attribute information. It is independent of the Style editor and of Property Selection.

A typical workflow is:

Select a MapObject.
Open its properties.
Use Metadata to manage Name and Description.
Use Property Selection, when available, to identify attributes for those semantic roles.
Use Attribute Table to inspect the object's actual attribute fields and values.
Use Style independently to manage its visual appearance.

The Attribute Table therefore provides the direct view of the object's stored attribute data, while Metadata and Property Selection provide the mechanisms for assigning and interpreting selected fields as semantic information.

LayerNode Style and Semantic Properties

The LayerNode Style and Semantic Properties panel provides a unified interface for controlling both the visual representation and the semantic information of the MapObject instances currently contained in a LayerNode.

The two areas are independent. Style controls the graphical appearance of objects, while Properties controls their semantic NAME and DESCRIPTION, exposed through MapObject.getName() and MapObject.getDescription(). These semantic properties are particularly useful for compatibility with external geographic applications such as Google Earth.

┌────────────────────────────────────────┐
│ LayerNode Style and Properties         │
│                                        │
│ STYLE                                  │
│                                        │
│ ○ Global style                         │
│ ○ Style by attribute                   │
│     Attribute: [ TYPE          ▼ ]     │
│ ○ Style by category                    │
│                                        │
│ PROPERTIES                             │
│                                        │
│ NAME                                   │
│ ○ Change name by attribute             │
│     Attribute: [ CITY          ▼ ]     │
│ ○ Restore original name                │
│                                        │
│ DESCRIPTION                            │
│ ○ Change description by attribute      │
│     Attribute: [ TYPE          ▼ ]     │
│ ○ Restore original description         │
│                                        │
│ Changes apply only to objects          │
│ currently in the layer.                │
└────────────────────────────────────────┘

Style

The Style section provides three mutually exclusive modes:

Global Style assigns the same style to all objects in the layer.
Style by Category assigns different styles to the categories contained in the layer. If fewer styles are available than categories, the available styles are reused cyclically.
Style by Attribute groups objects according to the distinct values of a selected attribute and assigns a style to each group. Missing, null, empty, or whitespace-only values are treated as a single MISSING group.

Semantic Properties

The Properties section provides independent operations for NAME and DESCRIPTION.

A selected attribute can be used to replace the corresponding semantic value of each applicable object. If the selected attribute is missing or has no usable value, the existing NAME or DESCRIPTION is preserved.

Before the first modification, the original NAME and DESCRIPTION values are stored using the stable MapObject ID. This allows the original values to be restored even if objects are subsequently deleted or their position within the layer changes.

Objects Added Later

Property operations are one-time operations applied only to the objects currently present in the layer.

Objects added later are not automatically modified. The user must explicitly repeat the operation if newly added objects are also to be processed.

This design avoids permanent listeners or automatic synchronization mechanisms and keeps the behaviour explicit and predictable.

Independence of Style and Properties

The Style and Properties systems operate independently.

Changing the visual style does not modify the semantic NAME or DESCRIPTION, while changing NAME or DESCRIPTION does not affect the visual style.

The panel therefore provides a high-level control point at the LayerNode level while preserving the existing RootNode → LayerNode → CategoryNode → ObjectNode → MapObject hierarchy.

CategoryNode and ObjectNode Style

The CategoryNode and ObjectNode Style panel provides a unified interface for customizing the visual appearance of map objects.

The same style editor is used at two different levels of the node hierarchy:

CategoryNode — changes the style of all MapObject instances belonging to the category.
ObjectNode — changes the style of one individual MapObject.

The relationship can be represented as follows:

LayerNode
   │
   ├── CategoryNode ──────────► Style applied to all objects
   │       │
   │       ├── ObjectNode ────► Style of Object 1
   │       ├── ObjectNode ────► Style of Object 2
   │       └── ObjectNode ────► Style of Object 3
   │
   └── CategoryNode ──────────► Style applied to all objects
           │
           ├── ObjectNode ────► Style of Object 4
           └── ObjectNode ────► Style of Object 5

Therefore, a style operation performed on a CategoryNode affects every MapObject belonging to that category, while an operation performed on an ObjectNode affects only its individual MapObject.

The options displayed depend on the type of object being edited.

┌──────────────────────────────────────────────────────────┐
│                  UNIFIED STYLE EDITOR                    │
├──────────────────────────────────────────────────────────┤
│ POINT        Symbol [ ● ▼ ]       Rotation [  0  ]       │
│ LINE         Color  [ ████ ]      Width    [ 1.0 ]       │
│ POLYGON      Fill   [ ████ ]                              │
│ TEXT         Font   [ Arial ▼ ]   Size [ 12 ]            │
│              Color  [ ████ ]                              │
│                                                          │
│ TRANSPARENCY                                             │
│                                                          │
│ Overall      ├────────────●────────────┤ 100%            │
│ □ Advanced                                               │
│                                                          │
│ Fill         ├────────────●────────────┤ 100%            │
│ Stroke       ├────────────●────────────┤ 100%            │
│ Text         ├────────────●────────────┤ 100%            │
│ Image        ├────────────●────────────┤ 100%            │
├──────────────────────────────────────────────────────────┤
│                              [ Restore ]    [ Apply ]     │
└──────────────────────────────────────────────────────────┘

Point Symbols

For point objects, the style editor allows you to choose the symbol used to represent the feature and set its rotation. Different symbols can therefore be used for different types of locations, while directional symbols can be oriented according to their actual direction.

Lines

For line features, you can choose the line color and adjust its width. These settings can be used to distinguish different types of routes, tracks, boundaries, or other linear features.

Polygons

For polygon features, you can choose the fill color. The line settings can also be used to control the appearance of the polygon outline, allowing areas to be displayed with different colors while maintaining a clearly visible boundary.

Labels

The label options allow you to choose the font, size, and color used for text associated with map objects. These settings can improve readability and provide a distinctive appearance for different types of information.

Transparency

The transparency section allows map elements to be displayed partially transparent.

An overall transparency value can be applied to the object. Advanced options allow the transparency of individual components, such as fill, outline, text, and images, to be adjusted separately.

This is particularly useful when working with overlapping map elements or when the underlying map needs to remain visible.

Applying the Changes

Changes made in the style editor are not applied immediately. The different options can be adjusted freely and reviewed before confirming them with Apply.

The scope of the operation depends on the node from which the style editor is opened:

For an ObjectNode, the selected style is applied only to that single MapObject.
For a CategoryNode, the selected style is applied to all MapObject instances belonging to that category.

The Restore Style command restores the standard style settings.

The panel therefore provides a consistent way to control the visual appearance of map data while respecting the hierarchy of MapNavigator: an ObjectNode controls one object, whereas a CategoryNode controls all objects belonging to the category.

Mapzen Terrain Integration

The integration of Mapzen terrain tiles into MapNavigator represents an important step beyond conventional 2D map display. MapNavigator can work directly with real elevation data, allowing terrain to be visualized and analyzed in three dimensions.

The terrain data is based on Mapzen Terrarium Terrain Tiles, a global elevation dataset distributed through Amazon S3. The dataset is publicly available through the AWS Open Data Registry – Terrain Tiles.

The system is based on three main components:

DEM-to-rendering pipeline
Elevation data is decoded directly from Terrarium tiles, converting pixel values into real elevations.
Multi-level tile caching
Precomputed lookup tables (LUTs) and an intelligent memory/disk cache keep terrain rendering responsive during navigation.
Realistic hillshading
A 3D-style shading system simulates illumination across the terrain, improving depth and readability.

Why Terrain Integration Matters

This integration extends MapNavigator beyond conventional 2D mapping and provides a foundation for:

advanced geographic applications;
terrain analysis, including slope, aspect and surface characteristics;
scientific visualization, such as geology, glaciology and landscape planning.

The Topographic Color LUT

Terrain rendering uses a 256-color lookup table (LUT), with approximately 92 significant color stops, designed to represent elevation ranges naturally.

Each elevation is mapped to a predefined color without requiring expensive color calculations during rendering.

Elevation	Typical colors	Interpretation
−11,000 to −6,000 m	Dark blue	Deep ocean trenches
−6,000 to −200 m	Blue → turquoise	Deep ocean
−200 to 0 m	Turquoise → sand	Coastal areas
0 to 100 m	Bright green	Lowlands
100 to 600 m	Green → ochre	Hills
600 to 2,500 m	Ochre → gray	Mountains
2,500 to 5,000 m	Gray	High mountains
5,000 to 8,849 m	White	Snow and glaciers

Multi-Level Tile Cache

The image cache is a fundamental component of the terrain rendering system. It uses three levels:

Memory cache (L1)
Recently used tiles are kept in RAM using an LRU (Least Recently Used) policy, providing immediate access.
Disk cache (L2)
Tiles are stored persistently in a temporary filesystem cache, avoiding repeated downloads between sessions.
Network (L3)
A tile is downloaded only when it is not available in either cache.

This architecture substantially reduces network requests and makes pan and zoom operations much smoother.

The cache also includes:

Asynchronous disk writing — tiles are saved in the background without blocking rendering.
Persistent LRU index — an index.txt file preserves tile usage information between sessions.
Automatic cleanup — least recently used tiles are removed when the cache reaches its maximum size.
Error resilience — corrupted cache files are detected and removed automatically.

Rendering Optimizations

Several optimizations reduce the computational cost of terrain rendering.

Color Cache

Each elevation is converted to a color only once. Subsequent requests for the same elevation, rounded to 0.1 m, are served in O(1) time.

The typical cache hit rate is approximately 97–98% on real terrain tiles.

Precomputed LUT

The 256-color terrain LUT is generated once at application startup, avoiding repeated color calculations during rendering.

Gamma LUT

Gamma correction, used to obtain more natural hillshading, is based on a precomputed table containing 4,096 values.

Tile-Border Gradients

Terrain rendering uses asymmetric gradients at tile borders. Forward/backward differences reduce visible seams between adjacent elevation tiles.

Technical Limitations

Limitation	Detail	Impact
Fixed tile size	256 × 256 pixels	Pixelation may become visible at very high zoom levels
Vertical accuracy	Approximately 0.1 m theoretical resolution, limited by PNG encoding and source data	Practical errors of about ±1–2 m may occur on complex terrain
No native hydrography	Terrarium elevation data does not contain rivers and lakes	Separate OSM or other overlays are required
Memory usage	About 524 KB for DEM data + about 256 KB for the rendered image per tile	About 6 MB for eight visible tiles

Operational Limitations

No progressive streaming: a complete tile must be downloaded before it can be rendered.
CPU-intensive rendering: hillshading and terrain calculations are performed by the CPU rather than the GPU.
Flat-earth rendering: the Earth's curvature is not considered at large scales, so distortion becomes relevant beyond regional-scale views.

Mapzen Terrarium Data Limitations

The underlying Terrarium elevation data is derived from SRTM and has the following limitations:

Horizontal resolution: approximately 30 m per pixel in the source data.
Geographic coverage: SRTM coverage is generally limited to approximately 56°S–60°N.
Data artifacts: some areas may contain gaps or artifacts resulting from the original elevation data, including historical cloud-related limitations in certain regions.

Overview

The Attribute Filter searches the objects of the selected vector layer according to their attribute values. It provides a graphical query builder, while the Query text area contains the actual expression that is executed.

After execution, matching objects are highlighted and the number of matches is displayed.

Selecting the Layer

Use the Layer drop-down list to select the vector layer to query.

When the selected layer changes, the objects and available fields are rebuilt, the previous query is cleared, and the result counter is reset.

Building a Condition

The Condition section contains:

Field — the attribute to test.
Operator — the comparison to perform.
Value — the value to compare.

Click Add a condition to insert the condition into the Query area.

String values are automatically quoted, including values containing spaces such as "New York".

Operators

Attribute type	Operators
String	`=`, `!=`, `contains`, `starts with`, `ends with`
Numeric	`=`, `!=`, `<`, `<=`, `>`, `>=`
Date	`=`, `!=`, `<`, `<=`, `>`, `>=`
Boolean	`=`, `!=`

String comparison is case-sensitive. Boolean values are true and false. Dates are documented by the implementation as yyyy-MM-dd.

Combining Conditions

The AND, OR, and NOT buttons insert logical operators.

AND — both conditions must be true.
OR — at least one condition must be true.
NOT — negates the following condition.

Parentheses can be used to control grouping.

```text
(population > 10000) AND (landuse = "industrial")

Wiki: Map Navigator Intro
Wiki: Nodes, Objects and Data Structure

Geo Arbores Wiki

Documentation

Documentation

Contents

* Nodes, Objects and Data Structure

* Manage Metadata

* Attribute Table

* LayerNode Style and Semantic Properties

* CategoryNode and ObjectNode Style

* Mapzen Terrain Integration

* Attribute Filter Panel

Nodes, Objects and Data Structure

Manage Metadata

Name and Description

Property Selection

Available Attributes

NAME and DESCRIPTION Selection

Selection and Application

Existing Assignments

Relationship with the Attribute Table

Metadata Tab

Optional Property Selection

Drawing Mode

Important Distinction

Typical Workflow

Attribute Table

Attributes

Attribute Table and Metadata

Imported Attributes

Export

Availability

LayerNode Style and Semantic Properties

Style

Semantic Properties

Objects Added Later

Independence of Style and Properties

CategoryNode and ObjectNode Style

Point Symbols

Lines

Polygons

Labels

Transparency

Applying the Changes

Mapzen Terrain Integration

Why Terrain Integration Matters

The Topographic Color LUT

Multi-Level Tile Cache

Rendering Optimizations

Color Cache

Precomputed LUT

Gamma LUT

Tile-Border Gradients

Technical Limitations

Operational Limitations

Mapzen Terrarium Data Limitations

MapNavigator Attribute Filter

Overview

Selecting the Layer

Building a Condition

Operators

Combining Conditions

Related