2.23.6.1. pycsamt.format.pointset#

PCPT - pyCSAMT Points: a tiny format for targets and points of interest.

PCPT is deliberately small. It carries a flat list of named positions - drill targets, planned collars, samples, anomalies, generic markers - each with a location and optional depth window, so a map or a 3-D scene can be annotated independently of a full pycsamt.format.borehole document. No trajectory, no interval logs, no vocabularies.

Canonical encoding is UTF-8 JSON, canonical extension .pcpt.json. CSV and spreadsheet importers resolve the same canonical fields through a small alias table.

Functions

point_set_from_dict(payload)

Build and validate a PointSet from a dict.

point_set_to_dict(point_set)

Return a canonical JSON-safe dict for point_set.

points_from_csv(path, *[, columns, crs, ...])

Import a points CSV (one point per row).

points_from_xlsx(source, *[, sheet, ...])

Import points from one worksheet of an .xlsx workbook.

read_points(path)

Read a .pcpt.json file.

write_points(point_set, path)

Write point_set as canonical .pcpt.json.

Classes

Point(id[, name, x, y, longitude, latitude, ...])

One named position with an optional depth window.

PointSet(document_id, created_at, ...[, ...])

A validated flat list of points sharing one CRS.

Exceptions

PointSetValidationError

Raised when a PCPT document fails validation.
class pycsamt.format.pointset.Point(id, name='', x=None, y=None, longitude=None, latitude=None, z=None, depth_top=None, depth_bottom=None, kind='poi', symbol='circle', color=None, note='', category='', properties=<factory>)[source]

Bases: PyCSAMTObject

One named position with an optional depth window.

Parameters:
id: str
name: str = ''
x: float | None = None
y: float | None = None
longitude: float | None = None
latitude: float | None = None
z: float | None = None
depth_top: float | None = None
depth_bottom: float | None = None
kind: str = 'poi'
symbol: str = 'circle'
color: str | None = None
note: str = ''
category: str = ''
properties: dict[str, Any]
issues()[source]
Return type:

list[str]

class pycsamt.format.pointset.PointSet(document_id, created_at, created_by, crs, points, pcpt_version='0.1.0', title='', description='', metadata=<factory>)[source]

Bases: PyCSAMTObject, MetadataMixin

A validated flat list of points sharing one CRS.

Parameters:
document_id: str
created_at: str
created_by: str
crs: str
points: list[Point]
pcpt_version: str = '0.1.0'
title: str = ''
description: str = ''
metadata: dict[str, Any]
issues()[source]
Return type:

list[str]

validate()[source]

Validate object state.

Subclasses can override this hook. The base implementation intentionally accepts all states.

Return type:

None

lonlat()[source]

Return {id: (lat, lon)} for every locatable point.

Return type:

dict[str, tuple[float, float]]

exception pycsamt.format.pointset.PointSetValidationError[source]

Bases: ValueError

Raised when a PCPT document fails validation.

pycsamt.format.pointset.read_points(path)[source]

Read a .pcpt.json file.

Parameters:

path (str | Path)

Return type:

PointSet

pycsamt.format.pointset.write_points(point_set, path)[source]

Write point_set as canonical .pcpt.json.

Parameters:
Return type:

Path

pycsamt.format.pointset.points_from_csv(path, *, columns=None, crs=None, document_id=None)[source]

Import a points CSV (one point per row).

Parameters:
Return type:

PointSet

pycsamt.format.pointset.points_from_xlsx(source, *, sheet=None, header_row=None, columns=None, crs=None, document_id=None)[source]

Import points from one worksheet of an .xlsx workbook.

Parameters:
Return type:

PointSet

pycsamt.format.pointset.point_set_to_dict(point_set)[source]

Return a canonical JSON-safe dict for point_set.

Parameters:

point_set (PointSet)

Return type:

dict[str, Any]

pycsamt.format.pointset.point_set_from_dict(payload)[source]

Build and validate a PointSet from a dict.

Parameters:

payload (dict[str, Any])

Return type:

PointSet