Index

subsurfaceio.cross_section

CAD-native geotechnical cross-section export.

Place in-situ tests along a horizontal section, then write a DXF with strata and parameter columns. Build from a site investigation and export:

from subsurfaceio.cross_section import CrossSection

section = CrossSection.from_site(site)
section.to_dxf('section.dxf')

Modules:

Name	Description
`data_access`	Depth/elevation mapping and test data helpers for cross-section export.
`layouts`	Default column templates per in-situ test type.
`render`	Cross-section DXF rendering.

Classes:

Name	Description
`CrossSection`	Geotechnical cross-section definition for CAD export.
`CrossSectionStation`	One in-situ test placed along the section horizontal axis.
`CrossSectionTemplate`	Ordered column layout for one test type.
`PlotColumnSpec`	A parameter plot column (line/marker chart vs depth or elevation).
`PlotSeriesSpec`	One data series drawn inside a plot column.
`StrataColumnSpec`	A labeled strata interval column.

Attributes:

Name	Type	Description
`ColumnSpec`	`TypeAlias`	Discriminated plot or strata column in a template.
`DrawStyle`	`TypeAlias`	Line interpolation between samples.
`MarkerStyle`	`TypeAlias`	Marker drawn at each sample.
`MergedTestData`	`TypeAlias`	Column-oriented raw and interpretation fields for one test.
`VerticalAxis`	`TypeAlias`	Section vertical coordinate; depth increases downward.
`XScale`	`TypeAlias`	Horizontal axis scale for a plot column.

ColumnSpec `module-attribute`

ColumnSpec: TypeAlias = Annotated[
    PlotColumnSpec | StrataColumnSpec,
    Field(discriminator="column_type"),
]

Discriminated plot or strata column in a template.

DrawStyle `module-attribute`

DrawStyle: TypeAlias = Literal['default', 'steps-post']

Line interpolation between samples.

MarkerStyle `module-attribute`

MarkerStyle: TypeAlias = Literal['none', 'circle', 'x']

Marker drawn at each sample.

MergedTestData `module-attribute`

MergedTestData: TypeAlias = dict[str, list[Any]]

Column-oriented raw and interpretation fields for one test.

VerticalAxis `module-attribute`

VerticalAxis: TypeAlias = Literal['depth', 'elevation']

Section vertical coordinate; depth increases downward.

XScale `module-attribute`

XScale: TypeAlias = Literal['linear', 'log']

Horizontal axis scale for a plot column.

CrossSection `pydantic-model`

Bases: BaseModel

Geotechnical cross-section definition for CAD export.

Coordinates are in meters. Create with from_site, then call to_dxf to write a DXF file.

Attributes:

Name	Type	Description
`project_metadata`	`ProjectMetadata \| None`	Copied from the site when built with `from_site`.
`stations`	`list[CrossSectionStation]`	Tests placed along the section.
`vertical`	`VerticalAxis`	Vertical axis; `depth` or `elevation`.
`template_overrides`	`dict[str, CrossSectionTemplate]`	Per-test-type column layouts replacing defaults.
`y_top_m`	`float \| None`	Optional section-wide top elevation/depth bound (m).
`y_bottom_m`	`float \| None`	Optional section-wide bottom elevation/depth bound (m).
`strata_label_height_m`	`float`	DXF text height for strata labels.
`axis_width_m`	`float`	Width of the shared vertical axis gutter (m).
`station_gap_m`	`float`	Horizontal gap inserted between auto-placed stations (m).

Fields:

project_metadata (ProjectMetadata | None)
stations (list[CrossSectionStation])
vertical (VerticalAxis)
template_overrides (dict[str, CrossSectionTemplate])
y_top_m (float | None)
y_bottom_m (float | None)
strata_label_height_m (float)
axis_width_m (float)
station_gap_m (float)

axis_width_m `pydantic-field`

axis_width_m: float = 1.0

Width of the shared vertical axis gutter (m).

project_metadata `pydantic-field`

project_metadata: ProjectMetadata | None = None

station_gap_m `pydantic-field`

station_gap_m: float = 2.0

Horizontal gap inserted between auto-placed stations (m).

stations `pydantic-field`

stations: list[CrossSectionStation]

strata_label_height_m `pydantic-field`

strata_label_height_m: float = 0.25

template_overrides `pydantic-field`

template_overrides: dict[str, CrossSectionTemplate]

vertical `pydantic-field`

vertical: VerticalAxis = 'elevation'

y_bottom_m `pydantic-field`

y_bottom_m: float | None = None

Optional section-wide bottom elevation/depth bound (m).

y_top_m `pydantic-field`

y_top_m: float | None = None

Optional section-wide top elevation/depth bound (m).

from_site `classmethod`

from_site(
    site: SiteInvestigation,
    stations: list[CrossSectionStation] | None = None,
    *,
    vertical: VerticalAxis = "elevation",
    **kwargs: Any
) -> Self

Build a cross-section from a site investigation.

When stations is omitted, one station is created per in-situ test on site, laid out left-to-right using each template width plus station_gap_m. Filter site first with get_tests_by_ids when only a subset should appear on the section.

Parameters:

Name	Type	Description	Default
`site`	`SiteInvestigation`	Site investigation supplying tests and project metadata.	required
`stations`	`list[CrossSectionStation] \| None`	Optional explicit station placements. When omitted, one station is created per in-situ test.	`None`
`vertical`	`VerticalAxis`	Vertical axis; `depth` or `elevation`.	`'elevation'`
`**kwargs`	`Any`	Extra `CrossSection` fields such as `station_gap_m`.	`{}`

Returns:

Type	Description
`Self`	A section bound to `site`, ready for `to_dxf`.

resolve_template

resolve_template(test_type: str) -> CrossSectionTemplate

Return the column template for test_type.

Parameters:

Name	Type	Description	Default
`test_type`	`str`	In-situ test type code such as `CPT` or `BORH`.	required

Returns:

Type	Description
`CrossSectionTemplate`	Override from `template_overrides`, or the package default.

station_width_m

station_width_m(test_type: str) -> float

Total rendered width of one station for test_type.

Parameters:

Name	Type	Description	Default
`test_type`	`str`	In-situ test type code such as `CPT` or `BORH`.	required

Returns:

Type	Description
`float`	Sum of column widths in the resolved template, in meters.

to_dxf

to_dxf(path: str | Path) -> None

Export this section to a DXF file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Output DXF path.	required

Raises:

Type	Description
`ValueError`	If the section was not created with `from_site`.

CrossSectionStation `pydantic-model`

Bases: BaseModel

One in-situ test placed along the section horizontal axis.

Attributes:

Name	Type	Description
`test_id`	`str`	In-situ test identifier.
`x_m`	`float`	Left edge of the station in section meters.

Fields:

test_id (str)
x_m (float)

test_id `pydantic-field`

test_id: str

x_m `pydantic-field`

x_m: float

Left edge of the station in section meters.

CrossSectionTemplate `pydantic-model`

Bases: BaseModel

Ordered column layout for one test type.

Attributes:

Name	Type	Description
`columns`	`list[ColumnSpec]`	Plot and strata columns from left to right.

Fields:

columns (list[ColumnSpec])

columns `pydantic-field`

columns: list[ColumnSpec]

PlotColumnSpec `pydantic-model`

Bases: BaseModel

A parameter plot column (line/marker chart vs depth or elevation).

Attributes:

Name	Type	Description
`column_type`	`Literal['plot']`	Union tag; must be `plot`.
`width_m`	`float`	Column width in section meters.
`series`	`list[PlotSeriesSpec]`	Data series drawn in this column.
`x_scale`	`XScale`	Horizontal axis scale.
`x_min`	`float \| None`	Optional lower x-limit.
`x_max`	`float \| None`	Optional upper x-limit.
`invert_x`	`bool`	If True, the x-axis runs right to left.
`title`	`str \| None`	Column header, or `None` for no title.
`reference_lines`	`list[float]`	Vertical reference values in data units.

Fields:

column_type (Literal['plot'])
width_m (float)
series (list[PlotSeriesSpec])
x_scale (XScale)
x_min (float | None)
x_max (float | None)
invert_x (bool)
title (str | None)
reference_lines (list[float])

column_type `pydantic-field`

column_type: Literal['plot'] = 'plot'

invert_x `pydantic-field`

invert_x: bool = False

reference_lines `pydantic-field`

reference_lines: list[float]

series `pydantic-field`

series: list[PlotSeriesSpec]

title `pydantic-field`

title: str | None = None

width_m `pydantic-field`

width_m: float

x_max `pydantic-field`

x_max: float | None = None

x_min `pydantic-field`

x_min: float | None = None

x_scale `pydantic-field`

x_scale: XScale = 'linear'

PlotSeriesSpec `pydantic-model`

Bases: BaseModel

One data series drawn inside a plot column.

Attributes:

Name	Type	Description
`x_field`	`str`	Data field plotted on the horizontal axis.
`y_field`	`str`	Vertical field; typically `depth`.
`color`	`int`	ACI color index.
`marker`	`MarkerStyle`	Marker drawn at samples.
`drawstyle`	`DrawStyle`	Line interpolation style.

Fields:

x_field (str)
y_field (str)
color (int)
marker (MarkerStyle)
drawstyle (DrawStyle)

color `pydantic-field`

color: int = 7

drawstyle `pydantic-field`

drawstyle: DrawStyle = 'default'

marker `pydantic-field`

marker: MarkerStyle = 'none'

x_field `pydantic-field`

x_field: str

y_field `pydantic-field`

y_field: str = 'depth'

StrataColumnSpec `pydantic-model`

Bases: BaseModel

A labeled strata interval column.

Attributes:

Name	Type	Description
`column_type`	`Literal['strata']`	Union tag; must be `strata`.
`width_m`	`float`	Column width in section meters.

Fields:

column_type (Literal['strata'])
width_m (float)

column_type `pydantic-field`

column_type: Literal['strata'] = 'strata'

width_m `pydantic-field`

width_m: float = 1.5

Index

subsurfaceio.cross_section

ColumnSpec module-attribute

DrawStyle module-attribute

MarkerStyle module-attribute

MergedTestData module-attribute

VerticalAxis module-attribute

XScale module-attribute

CrossSection pydantic-model

axis_width_m pydantic-field

project_metadata pydantic-field

station_gap_m pydantic-field

stations pydantic-field

strata_label_height_m pydantic-field

template_overrides pydantic-field

vertical pydantic-field

y_bottom_m pydantic-field

y_top_m pydantic-field

from_site classmethod

resolve_template

station_width_m

to_dxf

CrossSectionStation pydantic-model

test_id pydantic-field

x_m pydantic-field

CrossSectionTemplate pydantic-model

columns pydantic-field

PlotColumnSpec pydantic-model

column_type pydantic-field

invert_x pydantic-field

reference_lines pydantic-field

series pydantic-field

title pydantic-field

width_m pydantic-field

x_max pydantic-field

x_min pydantic-field

x_scale pydantic-field

PlotSeriesSpec pydantic-model

color pydantic-field

drawstyle pydantic-field

marker pydantic-field

x_field pydantic-field

y_field pydantic-field

StrataColumnSpec pydantic-model

column_type pydantic-field

width_m pydantic-field

ColumnSpec `module-attribute`

DrawStyle `module-attribute`

MarkerStyle `module-attribute`

MergedTestData `module-attribute`

VerticalAxis `module-attribute`

XScale `module-attribute`

CrossSection `pydantic-model`

axis_width_m `pydantic-field`

project_metadata `pydantic-field`

station_gap_m `pydantic-field`

stations `pydantic-field`

strata_label_height_m `pydantic-field`

template_overrides `pydantic-field`

vertical `pydantic-field`

y_bottom_m `pydantic-field`

y_top_m `pydantic-field`

from_site `classmethod`

CrossSectionStation `pydantic-model`

test_id `pydantic-field`

x_m `pydantic-field`

CrossSectionTemplate `pydantic-model`

columns `pydantic-field`

PlotColumnSpec `pydantic-model`

column_type `pydantic-field`

invert_x `pydantic-field`

reference_lines `pydantic-field`

series `pydantic-field`

title `pydantic-field`

width_m `pydantic-field`

x_max `pydantic-field`

x_min `pydantic-field`

x_scale `pydantic-field`

PlotSeriesSpec `pydantic-model`

color `pydantic-field`

drawstyle `pydantic-field`

marker `pydantic-field`

x_field `pydantic-field`

y_field `pydantic-field`

StrataColumnSpec `pydantic-model`

column_type `pydantic-field`

width_m `pydantic-field`