pygcd 0.3.post1

A simple python module to parse GOCAD ASCII exports

PyGCD

Read & convert GOCAD ASCII exports.

It is based on the documentation harvested on the web here and there, recycling some of the coseis routines.

pygcd can read GOCAD objects:

• TSurf
• TSolid
• Vset
• PLine
• Well
• Voxet
• GSurf
• SGrid

and knows how to serve them as third-party objects:

• Python objects
• geopandas.GeoDataFrame (requires geopandas)
• pyvista.DataObject (requires pyvista)
• lasio log files (requires lasio)

Summary

• Installation
• Quickstart
  • SIG converting
  • 3D rendering
  • Well curves
• Documentation
• What's next
• Contributing

Installation

Latest release can be installed using:

pip install pygcd 

Additional dependencies (pyvista, geopandas, ...) are required for serving the output into third-party formats.

pip install pygcd[drivers]

Quickstart

Basic reading

import pygcd

blocks = pygcd.read(filename)

with blocks a list of Objects with the following structure:

(
    name: str,
    geometry: Enum
    version: str
    fields: dict

    [...] # extra based on geometry
)

SIG converting

import pygcd

df = pygcd.read(filename, wrapper='geopandas')
df = df[df.geometry!=None]  # remove unsupported features

from pathlib import Path
outfile = Path(filename).with_suffix('.geojson').as_posix()
df.to_file(outfile)  # write everything "as is"

# or filter by geometry:
df['geom_type'] = [g.type for g in df.geometry]
for label, group in df.groupby('geom_type'):
    outfile = Path(filename).with_suffix(f'.{label}.shp').as_posix()
    group.to_file(outfile)

3D rendering

import pygcd
vtm = pygcd.read(filename, wrapper='pyvista')
vtm.plot(multi_colors=True)

LAS export

import pygcd
las = pygcd.read(filename, geometries=["Well"], wrapper='las')
for l in las:
   file = l.well.WELL.value + ".las"
   l.write(file, version=2)

What's inside ?

pygcd offers 3 reading levels for ASCII files:

• def find(file:str) -> list[str]: splits file content into single object text chunks
• def load(file:str) -> Dataset[Chunk]: read the header only with global attributes (name, geometry type, version, etc...)
• def read(file:str) -> Dataset[Object]: fully decode the objects with geometry specific attributes (points, cells, curves, etc...)

it provides 2 types of objects:

• class Dataset(list): a list with file reference
  • filename (str): the input file
  • convenient attributes getters (get block by name, select gemetry, ...)
  • to(self, wrapper:str) -> Any: method to cast objects into the supported wrappers ('pyvista', 'geopandas', ...)
• class Layer(object): an abstract generic class for GOCAD objects holding metadata:
  • name (str): the object name attribute
  • geometry (Enum): the GOCAD object type name
  • version (str): the GOCAD version of the geometry (unused feature)
  • fields (dict): the mapping of GOCAD object header properties

Layers

• class Chunk(Layer): a specialization for ascii text chunks
  • chunk (str): ascii block containing the object serialization
  • decode(self) -> Object: method to decode the geometry
• class Object(Layer): an abstract class for geometry-specific content
  • from_chunk(block:str)->Object: method to parse ascii chunk

Objects

• class Mesh(Object): for VSet, PLine, TSurf and TSolid
  • points (list): n-by-3 points coordinates
  • cells (list[tuple[int]]): list of point indices
  • point_data (dict): key-mapped point properties
  • cell_data (dict): key-mapped cell properties
• class Well(Object): for Well
  • collar (tuple[float]): 3 points coordinates (x,y,z)
  • path (list[tuple[float]]): n-by-4 trajectory coordinates (x, y, z, depth)
  • markers (list[namedtuple]): list of markers (name, zm:relative z + other extra fields)
  • zones (list[namedtuple]): list of zones/zones/trunks (name, zfrom:relative z, zto:relative z + other extra fields)
  • curves (list[namedtuple]): list of curves (i.e. diagraphies) along the path (name, zm:relative z, values:array + other extra fields)
• class Grid(Object): for Voxet, GSurf, SGrid
  • WIP: raise NotImpentedError()

TODO list

• Read geometries
  • TSurf
  • TSolid
  • Vset
  • PLine
  • Well
  • Voxet
  • GSurf
  • SGrid
• Read data properties
  • Atom/Vertex properties
  • Well properties
  • Well curves
  • Region properties (it is unclear how to use these ATM ...)
• Add dependency-free (or pure-python only) converters
  • GML/GeoJSON SIG formats
  • Generic mesh formats (using meshio?)
• Provide a GDAL driver for SIG native integration
• Provide a format conversion REST-API
  • GML/ GeoJSON
• Release publicly to PyPI

Feel free to contribute or open an issue to request a feature

Contributing

Any help with this tool is welcomed, see CONTRIBUTING.md for "guidelines" (strong word for a merely step-by-step how-to... feel free to contribute as you whishes).