pyramm

Python wrapper for the RAMM API.

Users must have their own login for the RAMM database.

Installation

pip install pyramm

Issues

Please submit an issue if you find a bug or have an idea for an improvement.

Initialise

You must first initialise the connection to the RAMM API as follows. Note that the database argument defaults to "SH New Zealand" if it is not provided.

from pyramm.api import Connection
conn = Connection(username, password, database="SH New Zealand")

Alternatively the username and password can be stored in file called .pyramm.ini. This file must be saved in the users home directory ("~" on linux) and contain the following:

[RAMM]
USERNAME = username
PASSWORD = password

You are then able to initialise the RAMM API connection without providing your login credentials each time.

from pyramm.api import Connection
conn = Connection()

Table and column names

A list of available tables can be accessed using:

table_names = conn.table_names()

A list of columns for a given table can be accessed using:

column_names = conn.column_names(table_name)

Table data

Some methods are attached to the Connection object to provide convenient access to selected RAMM tables. These helper methods implement some additional filtering (exposed as method arguments) and automatically set the DataFrame index to the correct table column(s).

Tables not listed in the sections below can be accessed using the general get_data() method:

df = conn.get_data(table_name)

General tables:

roadnames = conn.roadnames()

carrway = conn.carr_way(road_id=None)

surface_layer = conn.surface_layer(road_id=None)

surface_structure_cleaned = conn.surface_structure_cleaned()

surf_material_type = conn.surf_material_type()

HSD tables:

hsd_roughness = conn.hsd_roughness(road_id, latest=True, survey_year=None)

hsd_roughness_hdr = conn.hsd_roughness_hdr()

hsd_rutting = conn.hsd_rutting(road_id, latest=True, survey_year=None)

hsd_rutting_hdr = conn.hsd_rutting_hdr()

hsd_texture = conn.hsd_texture(road_id, latest=True, survey_year=None)

hsd_texture_hdr = conn.hsd_texture_hdr()

Centreline

The Centreline object is provided to:

assist with generating geometry for table entries (based on road_id, start_m and end_m values),

find the displacement (in metres) along the nearest geometry element given a point (latitude, longitude).

The base geometry used by the Centreline object is derived from the carr_way table.

Create a Centreline instance:

centreline = conn.centreline()

Append geometry to table:

For a table containing road_id, start_m and end_m columns, the geometry can be appended using the append_geometry() method:

df = centreline.append_geometry(df, geometry_type="wkt")

The geometry_type argument defaults to "wkt". This will provide a WKT LineString for each row.

Alternatively, geometry_type can be set to "coord" to append a northing and easting column to the DataFrame.

Find carriageway and position from point coordinates:

The carriageway and position information (e.g. Rs/Rp) can be determined for a point coordinate using the position() method:

point = Point((172.618567, -43.441594))  # Shapely Point object
position = centreline.position(point, point_crs=4326, road_id=None)

The point coordinate reference system defaults to WGS84 but can be adjusted using the point_crs argument. The value must be an integer corresponing to the EPSG code (e.g. 4326 for WGS84).

If the road_id argument is provided then the position will be determined only for the specified road. Otherwise the position will be determined for the nearest road.

Partial centreline

Sometimes it is necessary to match only to selected parts of the RAMM centreline. In this case a partial centreline can be generated and used for the matching:

# Generate a partial centreline containing only road_id 3656 between route position 10m
# and 100m:
partial_centreline = conn.centreline(lengths={3656: [10, 100]})

point = Point((172.608406, -43.451023))
position = partial_centreline.position(point)

The lengths argument is a Python dictionary containing road_id keys and start/end position pair values. Some examples include:

{3656: None} includes the entire centreline for road_id 3656.
{3656: [10, 100]} includes only the section of centreline for road_id 3656 between route position 10m and 100m.
{3656: [500, None]} includes only the section of centreline for road_id 3656 from route position 500m.

Geometry module

The geometry module includes some functions to generate spatial layers for use with GIS.

Chainage layer

A chainage layer can be generated for a given road_id or list of road_ids using build_chainage_layer.

The layer includes a marker line and a label line for each chainage point. The geometry is defined by a WKT string.

from pyramm.geometry import build_chainage_layer

# Generate chainage layer for road_id 655, the other values are the default:
chainage_layer = build_chainage_layer(
    centreline,
    road_id=655,
    length_m=1000,  # distance betrween chainage markers
    width_m=150,  # width of chainage marker line
    offset_m=0,  # offset of chainage marker line from centreline (can be negative)
    label_width_m=20,  # width of chainage label line
    label_offset_m=180,  # offset of chainage label line from centreline
)

chainage_layer.to_csv("chainage_layer.csv", index=False)