| Name | pyramm JSON |
| Version |
1.34
JSON |
| download |
| home_page | https://github.com/captif-nz/pyramm |
| Summary | Provides a wrapper to the RAMM API and additional tools for positional referencing |
| upload_time | 2024-02-11 21:50:16 |
| maintainer | |
| docs_url | None |
| author | John Bull |
| requires_python | >=3.8,<3.12 |
| license | MIT |
| keywords |
captif
ramm
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pyramm
<img align="right" src="https://github.com/captif-nz/pyramm/actions/workflows/push.yml/badge.svg">
Python wrapper for the [RAMM API](https://api.ramm.com/v1/documentation/index).
**Users must have their own login for the RAMM database.**
## Installation
```bash
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.
```python
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:
```ini
[RAMM]
USERNAME = username
PASSWORD = password
```
You are then able to initialise the RAMM API connection without providing your login
credentials each time.
```python
from pyramm.api import Connection
conn = Connection()
```
## Table and column names
A list of available tables can be accessed using:
```python
table_names = conn.table_names()
```
A list of columns for a given table can be accessed using:
```python
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:
```python
df = conn.get_data(table_name)
```
### General tables:
```python
roadnames = conn.roadnames()
```
```python
carrway = conn.carr_way(road_id=None)
```
```python
c_surface = conn.c_surface(road_id=None)
```
```python
top_surface = conn.top_surface()
```
```python
surf_material = conn.surf_material()
```
```python
surf_category = conn.surf_category()
```
```python
minor_structure = conn.minor_structure()
```
### HSD tables:
```python
hsd_roughness = conn.hsd_roughness(road_id, latest=True, survey_year=None)
```
```python
hsd_roughness_hdr = conn.hsd_roughness_hdr()
```
```python
hsd_rutting = conn.hsd_rutting(road_id, latest=True, survey_year=None)
```
```python
hsd_rutting_hdr = conn.hsd_rutting_hdr()
```
```python
hsd_texture = conn.hsd_texture(road_id, latest=True, survey_year=None)
```
```python
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 nearest geometry element to give a point (`latitude`, `longitude`), -->
- 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:
```python
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:
```python
df = centreline.append_geometry(df, geometry_type="wkt")
```
The `geometry_type` argument defaults to `"wkt"`. This will provide a
[WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)
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:
```python
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](https://epsg.io/) (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:
```python
# 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.
```python
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)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/captif-nz/pyramm",
"name": "pyramm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.12",
"maintainer_email": "",
"keywords": "CAPTIF,RAMM",
"author": "John Bull",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/3b/2e/a88b31454fa033aef79de031811e16cb402d71a91f0991774f1e30985173/pyramm-1.34.tar.gz",
"platform": null,
"description": "# pyramm\n\n<img align=\"right\" src=\"https://github.com/captif-nz/pyramm/actions/workflows/push.yml/badge.svg\">\n\n\nPython wrapper for the [RAMM API](https://api.ramm.com/v1/documentation/index).\n\n**Users must have their own login for the RAMM database.**\n\n## Installation\n\n```bash\npip install pyramm\n```\n\n## Issues\n\nPlease submit an issue if you find a bug or have an idea for an improvement.\n\n## Initialise\n\nYou must first initialise the connection to the RAMM API as follows. Note that the\n`database` argument defaults to `\"SH New Zealand\"` if it is not provided.\n\n```python\nfrom pyramm.api import Connection\nconn = Connection(username, password, database=\"SH New Zealand\")\n```\n\nAlternatively the username and password can be stored in file called `.pyramm.ini`. This\nfile must be saved in the users home directory (`\"~\"` on linux) and contain the following:\n\n```ini\n[RAMM]\nUSERNAME = username\nPASSWORD = password\n```\n\nYou are then able to initialise the RAMM API connection without providing your login\ncredentials each time.\n\n```python\nfrom pyramm.api import Connection\nconn = Connection()\n```\n\n## Table and column names\n\nA list of available tables can be accessed using:\n\n```python\ntable_names = conn.table_names()\n```\n\nA list of columns for a given table can be accessed using:\n\n```python\ncolumn_names = conn.column_names(table_name)\n```\n\n## Table data\n\nSome methods are attached to the `Connection` object to provide convenient access to\nselected RAMM tables. These helper methods implement some additional filtering (exposed\nas method arguments) and automatically set the DataFrame index to the correct table\ncolumn(s).\n\nTables not listed in the sections below can be accessed using the general `get_data()`\nmethod:\n\n```python\ndf = conn.get_data(table_name)\n```\n\n### General tables:\n```python\nroadnames = conn.roadnames()\n```\n```python\ncarrway = conn.carr_way(road_id=None)\n```\n```python\nc_surface = conn.c_surface(road_id=None)\n```\n```python\ntop_surface = conn.top_surface()\n```\n```python\nsurf_material = conn.surf_material()\n```\n```python\nsurf_category = conn.surf_category()\n```\n```python\nminor_structure = conn.minor_structure()\n```\n\n### HSD tables:\n\n```python\nhsd_roughness = conn.hsd_roughness(road_id, latest=True, survey_year=None)\n```\n```python\nhsd_roughness_hdr = conn.hsd_roughness_hdr()\n```\n```python\nhsd_rutting = conn.hsd_rutting(road_id, latest=True, survey_year=None)\n```\n```python\nhsd_rutting_hdr = conn.hsd_rutting_hdr()\n```\n```python\nhsd_texture = conn.hsd_texture(road_id, latest=True, survey_year=None)\n```\n```python\nhsd_texture_hdr = conn.hsd_texture_hdr()\n```\n\n## Centreline\n\nThe `Centreline` object is provided to:\n - assist with generating geometry for table entries (based on `road_id`, `start_m` and\n`end_m` values),\n <!-- - find the nearest geometry element to give a point (`latitude`, `longitude`), -->\n - find the displacement (in metres) along the nearest geometry element given a point\n(`latitude`, `longitude`).\n\nThe base geometry used by the `Centreline` object is derived from the `carr_way` table.\n\n### Create a Centreline instance:\n\n```python\ncentreline = conn.centreline()\n```\n\n### Append geometry to table:\n\nFor a table containing `road_id`, `start_m` and `end_m` columns, the geometry can be\nappended using the `append_geometry()` method:\n\n```python\ndf = centreline.append_geometry(df, geometry_type=\"wkt\")\n```\n\nThe `geometry_type` argument defaults to `\"wkt\"`. This will provide a\n[WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)\nLineString for each row.\n\nAlternatively, `geometry_type` can be set to `\"coord\"` to append\na `northing` and `easting` column to the DataFrame.\n\n### Find carriageway and position from point coordinates:\n\nThe carriageway and position information (e.g. Rs/Rp) can be determined for a point coordinate\nusing the `position()` method:\n\n```python\npoint = Point((172.618567, -43.441594)) # Shapely Point object\nposition = centreline.position(point, point_crs=4326, road_id=None)\n```\n\nThe point coordinate reference system defaults to WGS84 but can be adjusted using the\n`point_crs` argument. The value must be an integer corresponing to the\n[EPSG code](https://epsg.io/) (e.g. `4326` for WGS84).\n\nIf the `road_id` argument is provided then the position will be determined only for the\nspecified road. Otherwise the position will be determined for the nearest road.\n\n#### Partial centreline\n\nSometimes it is necessary to match only to selected parts of the RAMM centreline. In this\ncase a partial centreline can be generated and used for the matching:\n\n```python\n# Generate a partial centreline containing only road_id 3656 between route position 10m\n# and 100m:\npartial_centreline = conn.centreline(lengths={3656: [10, 100]})\n\npoint = Point((172.608406, -43.451023))\nposition = partial_centreline.position(point)\n```\n\nThe `lengths` argument is a Python dictionary containing `road_id` keys and start/end\nposition pair values. Some examples include:\n\n- `{3656: None}` includes the entire centreline for road_id 3656.\n- `{3656: [10, 100]}` includes only the section of centreline for road_id 3656 between route position 10m and 100m.\n- `{3656: [500, None]}` includes only the section of centreline for road_id 3656 from route position 500m.\n\n\n## Geometry module\n\nThe geometry module includes some functions to generate spatial layers for use\nwith GIS.\n\n### Chainage layer\n\nA chainage layer can be generated for a given road_id or list of road_ids using \n`build_chainage_layer`.\n\nThe layer includes a marker line and a label line for each chainage point. The \ngeometry is defined by a WKT string.\n\n```python\nfrom pyramm.geometry import build_chainage_layer\n\n# Generate chainage layer for road_id 655, the other values are the default:\nchainage_layer = build_chainage_layer(\n centreline,\n road_id=655,\n length_m=1000, # distance betrween chainage markers\n width_m=150, # width of chainage marker line\n offset_m=0, # offset of chainage marker line from centreline (can be negative)\n label_width_m=20, # width of chainage label line\n label_offset_m=180, # offset of chainage label line from centreline\n)\n\nchainage_layer.to_csv(\"chainage_layer.csv\", index=False)\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Provides a wrapper to the RAMM API and additional tools for positional referencing",
"version": "1.34",
"project_urls": {
"Homepage": "https://github.com/captif-nz/pyramm"
},
"split_keywords": [
"captif",
"ramm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae3a847c6c3b57673d36ebc4fe076175b60aace564da7b8ca4443fa814e38f43",
"md5": "d563be09b9d841076b2aaa2e3a3c9149",
"sha256": "3fad97ebda41c8327873fffaec3f375adb1139d360aab6c573d8229ffb56b6e8"
},
"downloads": -1,
"filename": "pyramm-1.34-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d563be09b9d841076b2aaa2e3a3c9149",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.12",
"size": 19894,
"upload_time": "2024-02-11T21:50:15",
"upload_time_iso_8601": "2024-02-11T21:50:15.017347Z",
"url": "https://files.pythonhosted.org/packages/ae/3a/847c6c3b57673d36ebc4fe076175b60aace564da7b8ca4443fa814e38f43/pyramm-1.34-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3b2ea88b31454fa033aef79de031811e16cb402d71a91f0991774f1e30985173",
"md5": "e92bb9d6526ec5063502dd7cabc41306",
"sha256": "8bb95c646e4020adf779098b060b0a35e3ad6e781392d134270227228fb08469"
},
"downloads": -1,
"filename": "pyramm-1.34.tar.gz",
"has_sig": false,
"md5_digest": "e92bb9d6526ec5063502dd7cabc41306",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.12",
"size": 19045,
"upload_time": "2024-02-11T21:50:16",
"upload_time_iso_8601": "2024-02-11T21:50:16.317137Z",
"url": "https://files.pythonhosted.org/packages/3b/2e/a88b31454fa033aef79de031811e16cb402d71a91f0991774f1e30985173/pyramm-1.34.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-11 21:50:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "captif-nz",
"github_project": "pyramm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyramm"
}
