2.23.6.2. pycsamt.format.geology#

PCGL - pyCSAMT Common Geology Legend.

PCGL is a small, portable document for the resistivity-to-geology interpretation legend that Map View’s Interpretation overlay applies to a 3-D block / fence / depth-slice / iso-surface view: an ordered table of named units, each with a resistivity range, a display colour, and an optional pattern/swatch reference, plus a little document metadata so the legend can travel between projects and applications on its own.

PCGL is deliberately a thin wrapper: the table itself is a pycsamt.geology.lithology.RockDatabase (already the resistivity-to-rock classification engine used across pycsamt), extended there with pattern_id/pattern_source fields. This module only adds the document envelope (id, timestamps, provenance, versioning) and canonical JSON (de)serialization on top of it – it introduces no parallel class hierarchy, the same way pycsamt.format.borehole bridges pycsamt.geology.Borehole rather than reimplementing it.

Canonical encoding is UTF-8 JSON, canonical extension .pcgl.json. A plain CSV with columns name, rho_min, rho_max, color, description, code, source, pattern_id, pattern_source (only name, rho_min, rho_max required) round-trips through GeologyLegend.from_csv() / GeologyLegend.to_csv() – the same columns pycsamt.geology.lithology.RockDatabase.from_csv() accepts, so an existing rock-property CSV already loads as a legend with no pattern assigned.

Example

>>> from pycsamt.format.geology import GeologyLegend
>>> legend = GeologyLegend.from_rock_database(title="Site A interpretation")
>>> legend.db.classify(250.0).name
'Granite (weathered)'
>>> legend.issues()
[]

Functions

legend_from_csv(path, **kwargs)

Module-level convenience alias for GeologyLegend.from_csv().

legend_from_dict(payload)

Build and validate a GeologyLegend from a dict.

legend_to_dict(legend)

Return a canonical JSON-safe dict for legend.

read_legend(path)

Read a .pcgl.json file.

write_legend(legend, path)

Write legend as canonical .pcgl.json.

Classes

GeologyLegend(document_id, created_at, ...)

A versioned, portable resistivity-to-geology legend document.

Exceptions

GeologyLegendValidationError

Raised when a PCGL document fails validation.
class pycsamt.format.geology.GeologyLegend(document_id, created_at, created_by, db, pcgl_version='0.1.0', title='', description='', rho_unit='ohm.m', metadata=<factory>)[source]

Bases: PyCSAMTObject, MetadataMixin

A versioned, portable resistivity-to-geology legend document.

Parameters:

  • document_id (str)

  • created_at (str) – ISO-8601 timestamp.

  • created_by (str) – Creating application, workflow step, or person (e.g. "auto-suggest", "manual", a user name).

  • db (RockDatabase) – The legend table itself – resistivity ranges, colours, and pattern references. See pycsamt.geology.lithology. RockDatabase.

  • pcgl_version (str)

  • title (str)

  • description (str)

  • rho_unit (str) – Resistivity unit the ranges are expressed in. PCGL 0.1 only defines "ohm.m" (linear ohm-metres); readers MUST reject any other value rather than silently reinterpreting the ranges.

  • metadata (dict[str, Any])

document_id: str
created_at: str
created_by: str
db: RockDatabase
pcgl_version: str = '0.1.0'
title: str = ''
description: str = ''
rho_unit: str = 'ohm.m'
metadata: dict[str, Any]
property entries: tuple[RockEntry, ...][source]
classify(rho_ohm_m, method='nearest')[source]
Parameters:
Return type:

RockEntry

classmethod from_rock_database(db=None, *, document_id=None, created_by='pycsamt', title='', description='')[source]

Wrap an existing (or the built-in default) rock database as a PCGL document, ready to write or hand to Map View.

Parameters:
Return type:

GeologyLegend

classmethod from_csv(path, *, document_id=None, created_by='pycsamt CSV importer', title='')[source]

Load a legend from a CSV (see module docstring for columns).

Parameters:
Return type:

GeologyLegend

to_csv(path)[source]

Write the legend table as CSV (document metadata is dropped; use write_legend() to keep it).

Parameters:

path (str | Path)

Return type:

Path

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

exception pycsamt.format.geology.GeologyLegendValidationError[source]

Bases: ValueError

Raised when a PCGL document fails validation.

pycsamt.format.geology.read_legend(path)[source]

Read a .pcgl.json file.

Parameters:

path (str | Path)

Return type:

GeologyLegend

pycsamt.format.geology.write_legend(legend, path)[source]

Write legend as canonical .pcgl.json.

Parameters:
Return type:

Path

pycsamt.format.geology.legend_from_csv(path, **kwargs)[source]

Module-level convenience alias for GeologyLegend.from_csv().

Parameters:
Return type:

GeologyLegend

pycsamt.format.geology.legend_to_dict(legend)[source]

Return a canonical JSON-safe dict for legend.

Parameters:

legend (GeologyLegend)

Return type:

dict[str, Any]

pycsamt.format.geology.legend_from_dict(payload)[source]

Build and validate a GeologyLegend from a dict.

Parameters:

payload (dict[str, Any])

Return type:

GeologyLegend