Scales

subsurfaceio.cross_section.render.scales

Coordinate transforms, axis ticks, and polyline helpers.

Functions:

Name	Description
`extend_steps_post_to_surface`	Prepend a surface point so steps-post series start at the top.
`format_tick_label`	Format a numeric tick label for DXF text entities.
`map_x_value`	Map a data x-value to a section horizontal coordinate.
`nice_axis_ticks`	Return evenly spaced major ticks covering a vertical range.
`nice_ceiling`	Round `value` up to a readable axis step.
`nice_linear_ticks`	Return evenly spaced major ticks covering a horizontal range.
`resolve_x_limits`	Resolve plot x-limits from data and optional column bounds.
`split_line_segments`	Split a polyline at null x-values into continuous segments.
`steps_post_polyline`	Build a matplotlib-style `steps-post` polyline.
`steps_post_polyline_segments`	Build `steps-post` segments, breaking on null x-values.
`x_tick_values`	Return x-axis tick values for a plot column.

extend_steps_post_to_surface

extend_steps_post_to_surface(
    xs: list[float | None],
    ys: list[float],
    *,
    surface_y: float
) -> tuple[list[float | None], list[float]]

Prepend a surface point so steps-post series start at the top.

Parameters:

Name	Type	Description	Default
`xs`	`list[float \| None]`	Mapped x-coordinates.	required
`ys`	`list[float]`	Section Y coordinates.	required
`surface_y`	`float`	Surface elevation or zero-depth Y.	required

Returns:

Type	Description
`tuple[list[float \| None], list[float]]`	Possibly extended `(xs, ys)` pair.

format_tick_label

format_tick_label(value: float) -> str

Format a numeric tick label for DXF text entities.

Parameters:

Name	Type	Description	Default
`value`	`float`	Tick value.	required

Returns:

Type	Description
`str`	Integer string when `value` is whole, otherwise `g` format.

map_x_value

map_x_value(
    value: float | None,
    *,
    x_left: float,
    width_m: float,
    x_min: float,
    x_max: float,
    x_scale: XScale = "linear",
    invert_x: bool = False
) -> float | None

Map a data x-value to a section horizontal coordinate.

Parameters:

Name	Type	Description	Default
`value`	`float \| None`	Data value, or `None` / NaN to skip.	required
`x_left`	`float`	Left edge of the plot column in section meters.	required
`width_m`	`float`	Column width in section meters.	required
`x_min`	`float`	Lower data limit of the column axis.	required
`x_max`	`float`	Upper data limit of the column axis.	required
`x_scale`	`XScale`	Horizontal axis scale.	`'linear'`
`invert_x`	`bool`	If True, map high data values toward `x_left`.	`False`

Returns:

Type	Description
`float \| None`	Section X, or `None` when the value cannot be mapped.

nice_axis_ticks

nice_axis_ticks(
    y_min: float, y_max: float, *, max_ticks: int = 10
) -> list[float]

Return evenly spaced major ticks covering a vertical range.

Parameters:

Name	Type	Description	Default
`y_min`	`float`	Lower bound.	required
`y_max`	`float`	Upper bound.	required
`max_ticks`	`int`	Target tick count used to choose the step.	`10`

Returns:

Type	Description
`list[float]`	Tick values covering `[y_min, y_max]`.

nice_ceiling

nice_ceiling(value: float, *, max_ticks: int = 5) -> float

Round value up to a readable axis step.

Parameters:

Name	Type	Description	Default
`value`	`float`	Positive data maximum.	required
`max_ticks`	`int`	Target tick count used to choose the step.	`5`

Returns:

Type	Description
`float`	Ceiling of `value` on a 1-2-5 step.

nice_linear_ticks

nice_linear_ticks(
    x_min: float, x_max: float, *, max_ticks: int = 5
) -> list[float]

Return evenly spaced major ticks covering a horizontal range.

Parameters:

Name	Type	Description	Default
`x_min`	`float`	Lower bound.	required
`x_max`	`float`	Upper bound.	required
`max_ticks`	`int`	Target tick count used to choose the step.	`5`

Returns:

Type	Description
`list[float]`	Tick values covering `[x_min, x_max]`.

resolve_x_limits

resolve_x_limits(
    values: list[float],
    x_min: float | None,
    x_max: float | None,
    *,
    x_scale: XScale = "linear"
) -> tuple[float, float]

Resolve plot x-limits from data and optional column bounds.

Parameters:

Name	Type	Description	Default
`values`	`list[float]`	Observed x-values (may include NaN).	required
`x_min`	`float \| None`	Optional lower bound from the column spec.	required
`x_max`	`float \| None`	Optional upper bound from the column spec.	required
`x_scale`	`XScale`	Horizontal axis scale.	`'linear'`

Returns:

Type	Description
`tuple[float, float]`	Resolved `(x_min, x_max)` used for mapping and ticks.

split_line_segments

split_line_segments(
    xs: list[float | None], ys: list[float]
) -> list[list[tuple[float, float]]]

Split a polyline at null x-values into continuous segments.

Parameters:

Name	Type	Description	Default
`xs`	`list[float \| None]`	Mapped x-coordinates; `None` breaks the line.	required
`ys`	`list[float]`	Section Y coordinates, same length as `xs`.	required

Returns:

Type	Description
`list[list[tuple[float, float]]]`	Polylines with at least two points each.

steps_post_polyline

steps_post_polyline(
    xs: list[float | None], ys: list[float]
) -> list[tuple[float, float]]

Build a matplotlib-style steps-post polyline.

Parameters:

Name	Type	Description	Default
`xs`	`list[float \| None]`	Mapped x-coordinates; `None` breaks the line.	required
`ys`	`list[float]`	Section Y coordinates.	required

Returns:

Type	Description
`list[tuple[float, float]]`	Flattened step vertices (gaps are not represented).

steps_post_polyline_segments

steps_post_polyline_segments(
    xs: list[float | None], ys: list[float]
) -> list[list[tuple[float, float]]]

Build steps-post segments, breaking on null x-values.

Parameters:

Name	Type	Description	Default
`xs`	`list[float \| None]`	Mapped x-coordinates; `None` breaks the line.	required
`ys`	`list[float]`	Section Y coordinates.	required

Returns:

Type	Description
`list[list[tuple[float, float]]]`	Step polylines with at least two points each.

x_tick_values

x_tick_values(
    x_min: float,
    x_max: float,
    *,
    x_scale: XScale = "linear",
    column_x_min: float | None = None,
    column_x_max: float | None = None,
    reference_lines: list[float] | None = None
) -> list[float]

Return x-axis tick values for a plot column.

Parameters:

Name	Type	Description	Default
`x_min`	`float`	Resolved lower data limit.	required
`x_max`	`float`	Resolved upper data limit.	required
`x_scale`	`XScale`	Horizontal axis scale.	`'linear'`
`column_x_min`	`float \| None`	Optional explicit lower bound from the column spec.	`None`
`column_x_max`	`float \| None`	Optional explicit upper bound from the column spec.	`None`
`reference_lines`	`list[float] \| None`	Vertical reference values always included as ticks.	`None`

Returns:

Type	Description
`list[float]`	Sorted tick values inside `[x_min, x_max]`.