You are viewing the documentation for the development build of POLARIS. Click here to view the stable version.

Import-Export

Import-Export#

The Polaris Supply (network) file is built on open data formats, so in general there is no need to export the data to other formats in order to read it in most available software.

However, there are three cases where importing/exporting models from/to simpler (text-based) formats is necessary:

Creating new Polaris models from supply data available from other tools.
Converting network data to a format adequate for version-control.
Sharing models with other tools that support standard formats.

Text-based files#

A custom text-based format for Polaris was created to represent complete Polaris supply files on a set of text-based files, where each data table is represented by two separate files:

A *.schema file with the table structure, including data type and SQL constraints such as whether which field should be not null, have a default value or be a unique identifier
A *.csv file with the contents of the table, where geometry fields are converted to Well-Known-Text (WKT)

The last file part of the text-based representation of Polaris supply files is the list of all SRIDs (projections) for each of the WKT geometries included in each one of the data tables.

This general format allows for the export of supply files with an arbitrary set of data tables, as there is no pre-defined structure for the text-based data.

The capability of importing supply files in this format is also built into polaris-studio, and extends the Polaris data model to include all additional tables exported to the format and any extra fields on existing tables.

GMNS#

The General Modeling Network Specification (GMNS) is the proposed industry standard for network data exchange. It is for modelling networks what GTFS is for transit data.

The Polaris GMNS importer and exporter target GMNS v0.97, the latest available version as of May 2026. The spec version supported is exposed as polaris.network.ie.gmns.GMNS_SPEC_VERSION and stamped onto each exported config.csv. Polaris does not validate exported folders against the specification at runtime - see “Validation” below.

Supported tables#

Status by GMNS table#
GMNS table	Imported	Exported	Notes
`config`	yes	yes	Drives unit handling (`short_length`, `long_length`, `speed`) and CRS resolution. When absent on import, legacy defaults (meter / kilometer / kph / WKT / EPSG:4326) are used and a warning is logged.
`use_definition`	yes (into `Use_Code`)	yes (from `Use_Code`)	The Polaris `Use_Code` table populates the `persons_per_vehicle` / `pce` columns with sensible defaults if it lacks the metadata.
`use_group`	yes (members unfolded into `Use_Code`)	empty placeholder	Polaris does not currently model use groups separately.
`node`	yes	yes	`ctrl_type` is mapped to / from the v0.97 `shared_categories` enum.
`link`	yes	yes	`directed` is required in v0.97; the exporter emits unidirectional rows and the importer respects the value when collapsing bidirectional pairs. AB/BA expansion encodes the Polaris `link` primary key as `2*link + dir` on export (default `config.id_type = "integer"`).
`geometry`	yes	yes	Geometries are emitted both inline on the link table and as a separate `geometry.csv` keyed via `geometry_id`.
`zone`	yes	yes	`super_zone` is preserved as an ad-hoc column when present.
`location`	yes	yes	Locations without coordinates are now supported (x/y are derived from the link geometry and `lr`). `gtfs_stop_id` is preserved when present.
`movement`	yes (overrides only)	yes	Movements are normally generated by Polaris’s consistency engine; a GMNS `movement.csv` is consumed as an override of `Connection.type`.
`segment`	yes (mapped to `Pocket`)	yes	`l_lanes_added` / `r_lanes_added` are converted to LEFT_TURN / RIGHT_TURN / LEFT_MERGE / RIGHT_MERGE pocket rows.
`signal_controller`, `signal_phase_mvmt`, `signal_timing_plan`, `signal_timing_phase`	no	yes	Exported from Polaris’s `Signal`, `Phasing`, `Timing` and nested-record tables. `timing_phase_id` on `signal_phase_mvmt.csv` is resolved by joining `(controller_id, signal_phase_num)`.
`lane`, `segment_lane`, `curb_seg`, `link_tod`, `segment_tod`, `lane_tod`, `segment_lane_tod`, `movement_tod`, `signal_coordination`, `signal_detector`, `time_set_definitions`	no (warning logged)	no	Polaris does not model these natively. If present on import, a warning is logged listing the skipped tables.

Importer#

The importer entry point is polaris.network.ie.import_export.NetworkImportExport, exposed as network.ie.from_gmns(folder, crs). Internally it runs the following steps in order:

import_config - reads config.csv (or falls back to legacy defaults).
import_use_definitions / import_use_groups.
import_nodes, import_links, import_zones, import_locations.
import_movements (overrides), import_segments (pockets).
Logs warnings for any present-but-unsupported tables.

Behavioural notes carried over from earlier versions:

All geometry coordinates are rounded to 6 digits after re-projection into the model’s CRS (precision ~ 1 micron in metric CRS, immaterial for modeling).
Bidirectional collapse: when two GMNS links describe the same node-pair in opposite directions and either both are flagged directed=true or directed is missing, the importer collapses them into a single Polaris bidirectional link.
Minimum lane count of 1 is enforced (OSM imports often omit lanes).
allowed_uses -> Polaris use; facility_type -> Polaris type; unrecognised facility types are added to Link_Type with rank 10 and default pocket configuration.
link length is recomputed from the imported geometry.
For locations: link and zone are recomputed from spatial joins. Importing a location requires non-empty Zone and Link tables.

OpenStreetMap#

OSM2GMNS remains the recommended path from OSM to a GMNS folder. Its outputs are pre-v0.97 (no config.csv, no directed column); the Polaris importer accepts these via its legacy fallback path with deprecation warnings.

Exporter#

The exporter entry point is network.ie.to_gmns(folder, crs). It writes the following files in order: config.csv, use_definition.csv, use_group.csv, link.csv + geometry.csv, node.csv, zone.csv, movement.csv, segment.csv, the four signal_*.csv files, and location.csv.

Notable transformations:

Each Polaris bidirectional link emits up to two GMNS rows. Their primary key follows link_id = 2 * polaris_link + dir (where dir = 0 for AB and 1 for BA). This scheme is reversed on import by import_movements / import_segments so that the movement and segment files round-trip back into Polaris.
All emitted link rows carry directed = True.
Lengths are converted to the GMNS unit (km by default); free-flow speeds to km/h.
node.ctrl_type is mapped to the v0.97 shared_categories.json#/ctrl_type enum.
movement.type is mapped to the v0.97 shared_categories.json#/movement_type enum (lower-case categories). mvmt_code is left blank because Polaris does not store the cardinal direction component.

Validation#

Polaris does not ship a runtime GMNS validator. To verify an exported folder against the spec, use one of the upstream tools:

gmnspy - gmnspy.in_out.read_gmns_network(data_directory=...) raises on schema violations.
The official frictionless CLI (frictionless validate) against the schemas published in zephyr-data-specs/GMNS/spec.

The polaris-studio test suite carries a small in-tests validator helper (tests/network/ie/_gmns_validation/) that cross-checks the exporter against a vendored copy of the v0.97 schemas, but that helper is not part of the installable package.