2.16.3.6. pycsamt.geology.patterns#

Pattern/swatch packs for the Interpretation legend’s pattern_id / pattern_source fields (see pycsamt.geology.lithology.RockEntry).

pycsamt never vendors a third-party geologic pattern set (e.g. the USGS FGDC “Digital Cartographic Standard for Geologic Map Symbolization” AI pack) – only the machinery to import one the user already downloaded and use it. PatternLibrary copies whatever is handed to it (a folder, a .zip, or a single PDF/AI sheet) into a small persistent cache so the app keeps working after the original download is deleted, mirroring the fetch/cache convention pycsamt.geology.rock_providers.RemoteRockPropertyProvider already uses for the rock database (~/.pycsamt/geology_patterns, override with $PYCSAMT_PATTERN_CACHE).

A named, third-party pattern sheet (a page of many drawn symbols, as FGDC-style packs ship them) carries no machine-readable per-symbol crop box or label – that information exists only as a human reading the page. So this module deliberately does not attempt to auto-slice one: PatternLibrary.import_pack() rasterizes each PDF/AI page to a reference image (via PyMuPDF, an optional dependency – install the patterns extra), and PatternLibrary.add_tile_from_crop() lets the application crop a named rectangle out of that image by hand, the same way a person would pick a swatch out of a printed legend sheet. builtin_pack() ships a small procedurally generated pattern set (diagonal lines, cross-hatch, dots, brick, …) that needs no import at all.

Functions

builtin_pack()

The always-available, zero-setup pattern pack -- a small set of neutral procedurally generated hatch/stipple/brick/dot tiles, not derived from any third-party source.

tile_stencil_array(path)

Read a tile PNG as an ink-density stencil: an H x W array of alpha-weighted darkness in [0, 1] (0 = no ink / paper, 1 = full ink), read from PatternTile.file.

Classes

PatternLibrary([cache_dir])

Manages persisted pattern packs under one cache directory.

PatternPack(id, name, source, imported_at, ...)

A named collection of PatternSheet / PatternTile, persisted under one directory in the pattern cache.

PatternSheet(id, file, source_file, page, ...)

One rasterized reference page (a source PDF/AI page rendered to PNG), the surface PatternLibrary.add_tile_from_crop() crops named swatches out of.

PatternTile(id, name, file[, color, ...])

One named, usable swatch -- a small PNG, optionally a plain solid colour instead of an image.

Exceptions

PatternImportError

Raised when a pattern-pack source cannot be imported.
class pycsamt.geology.patterns.PatternPack(id, name, source, imported_at, directory, sheets=<factory>, tiles=<factory>)[source]

Bases: object

A named collection of PatternSheet / PatternTile, persisted under one directory in the pattern cache.

Parameters:

  • id (str)

  • name (str)

  • source (str)

  • imported_at (str)

  • directory (Path)

  • sheets (list[PatternSheet])

  • tiles (list[PatternTile])

id: str
name: str
source: str
imported_at: str
directory: Path
sheets: list[PatternSheet]
tiles: list[PatternTile]
tile(tile_id)[source]
Parameters:

tile_id (str)

Return type:

PatternTile | None

sheet(sheet_id)[source]
Parameters:

sheet_id (str)

Return type:

PatternSheet | None

class pycsamt.geology.patterns.PatternSheet(id, file, source_file, page, width, height)[source]

Bases: object

One rasterized reference page (a source PDF/AI page rendered to PNG), the surface PatternLibrary.add_tile_from_crop() crops named swatches out of.

Parameters:
id: str
file: str
source_file: str
page: int
width: int
height: int
class pycsamt.geology.patterns.PatternTile(id, name, file, color=None, sheet_id=None, bbox=None)[source]

Bases: object

One named, usable swatch – a small PNG, optionally a plain solid colour instead of an image.

Parameters:
id: str
name: str
file: str
color: str | None = None
sheet_id: str | None = None
bbox: tuple[int, int, int, int] | None = None
class pycsamt.geology.patterns.PatternLibrary(cache_dir=None)[source]

Bases: object

Manages persisted pattern packs under one cache directory.

Parameters:

cache_dir (PathLike | None)

list_packs()[source]

Return {id, name, n_sheets, n_tiles} for every persisted pack, plus the always-available built-in pack first.

Return type:

list[dict[str, Any]]

load_pack(pack_id)[source]

Load a persisted pack by id, materializing builtin_pack into the cache on first request so every pack (built-in or imported) is read through the same on-disk path.

Parameters:

pack_id (str)

Return type:

PatternPack

import_pack(source, *, name=None, filename=None)[source]

Copy source into the persistent cache and rasterize any PDF/AI sheet it contains.

source is a folder, a .zip archive, a single PDF/AI file path, or raw bytes (with filename giving its name/kind, for an uploaded file). Returns the resulting PatternPack; raises PatternImportError on anything unusable, and raises ImportError (never silently degrades) when a PDF/AI sheet needs rasterizing but pymupdf is not installed.

Parameters:
Return type:

PatternPack

add_tile_from_crop(pack_id, sheet_id, bbox, name)[source]

Crop bbox (pixel x0, y0, x1, y1) out of sheet_id and save it as a new named tile in the pack.

Parameters:
Return type:

PatternTile

delete_tile(pack_id, tile_id)[source]
Parameters:
Return type:

None

exception pycsamt.geology.patterns.PatternImportError[source]

Bases: ValueError

Raised when a pattern-pack source cannot be imported.

pycsamt.geology.patterns.builtin_pack()[source]

The always-available, zero-setup pattern pack – a small set of neutral procedurally generated hatch/stipple/brick/dot tiles, not derived from any third-party source.

Return type:

PatternPack

pycsamt.geology.patterns.tile_stencil_array(path)[source]

Read a tile PNG as an ink-density stencil: an H x W array of alpha-weighted darkness in [0, 1] (0 = no ink / paper, 1 = full ink), read from PatternTile.file.

The tile’s own colour is discarded on purpose – a pattern is applied tinted by the legend’s assigned colour (see pycsamt.map.styles.pattern_band_stops()), not by whatever colour the source pack happened to draw its swatch in, so the same hatch/stipple/brick shape reads consistently whatever unit it is assigned to.

Parameters:

path (str | Path)