Skip to content

Polylines

Lines and polygons with one attribute row per feature.

Parameters:

Name Type Description Default
parts sequence of array_like

(m, 2) or (m, 3) vertices per part; 2D gets z = 0.

 required
closed bool or sequence of bool

Whether each part is a ring. Rings do not repeat their first vertex and need 3 vertices; open parts need 2.

 False
features sequence of int

Feature of each part, non-decreasing from 0. A feature with several parts is multipart; its rings bound an area by even-odd counting in plan, so a ring inside another is a hole. Defaults to one feature per part.

 required
attributes table-like or dict of arrays

One row per feature.

 required
crs str
required

bounds property 

bounds

(min, max) corners, None when empty.

closed property 

closed

Whether each part is a ring.

column_names property 

column_names

Names of the attribute columns.

coords property 

coords

(n, 3) vertices of all parts, one part after the other.

feature property 

feature

Feature of each part.

length_unit property 

length_unit

Unit of the coordinates, such as m or ft; None when not declared.

parts property 

parts

(m, 3) vertices per part.

units property 

units

Units of the attributes that have one; see Table.units.

x property 

x

x of each row's coordinates.

y property 

y

y of each row's coordinates.

z property 

z

z of each row's coordinates.

area method descriptor 

area()

Plan area of each feature: closed parts inside an odd number of the feature's other closed parts are holes and subtract. Parts of a feature must not cross.

contains method descriptor 

contains(points, *, feature=None)

Whether each point is inside a feature in plan.

Parameters:

Name Type Description Default
points (PointSet, BlockModel or array_like)

(n, 2) or (n, 3) coordinates; z is ignored.

 required
feature int

Feature to test; any feature by default.

 None

Returns:

Type Description
ndarray of bool

Inside means an odd number of the feature's closed parts hold the point, so a ring inside another is a hole. Open parts are ignored.

convert_units method descriptor 

convert_units(column, *, to)

New polylines with column converted to unit to; see Table.convert_units.

distance method descriptor 

distance(points, *, feature=None, signed=False)

Plan distance from each point to the nearest closed part.

Parameters:

Name Type Description Default
points (PointSet, BlockModel or array_like)

(n, 2) or (n, 3) coordinates; z is ignored.

 required
feature int

Feature whose closed parts count; all by default.

 None
signed bool

Negative inside, as contains.

 False

Returns:

Type Description
ndarray of float

drop_null 

drop_null(*columns)

Rows with a value in every one of columns, all columns by default.

filter method descriptor 

filter(mask)

Features where mask is true.

from_table staticmethod 

from_table(
    table,
    *,
    feature="ID",
    x="X",
    y="Y",
    z=None,
    part=None,
    closed=False,
    crs=None,
    length_unit=None,
)

Builds polylines from a long table with one row per vertex.

Parameters:

Name Type Description Default
table table - like

Any Arrow-compatible table (polars, pandas, pyarrow).

 required
feature str

Column identifying the feature of each vertex. Features are ordered by first appearance; a feature without rows cannot be expressed.

 "ID"
x str

Coordinate columns.

 "X", "Y"
y str

Coordinate columns.

 "X", "Y"
z str

Elevation column; z = 0 without it.

 None
part str

Column identifying the part within a feature, ordered by first appearance; without it each feature is one part.

 None
closed bool

Whether every part is a ring.

 False
crs str
None

Returns:

Type Description
Polylines

Vertices keep their row order within a part. Attributes, the feature column included, come from each feature's first row; the coordinate and part columns are dropped.

length method descriptor 

length()

3D length of each feature, closed parts with their closing segment.

locate method descriptor 

locate(points)

Feature holding each point in plan, as contains; the first one where features overlap and -1 outside all of them.

to_length_unit method descriptor 

to_length_unit(unit, *, crs=None)

A copy with the coordinates converted to unit, the new length unit.

Parameters:

Name Type Description Default
unit str

A length unit, such as m or ft.

 required
crs str

The CRS of the converted coordinates; required when the coordinates have a CRS, which a change of unit changes.

 None

Raises:

Type Description
InvalidInput

Without a length unit to convert from, or with a CRS and no crs.

to_points method descriptor 

to_points()

One point per vertex with feature and part indices and the feature's attributes.

to_table method descriptor 

to_table()

One row per feature: the attributes, geometry as a list of parts, each a list of {x, y, z} structs, and closed as a list of flags.

with_attributes method descriptor 

with_attributes(table)

New polylines with table as the attributes, one row per feature.

with_column method descriptor 

with_column(name, values, *, unit=None)

New polylines with the per-feature attribute name added or replaced, in unit or else the unit values carries.

with_columns method descriptor 

with_columns(data)

New polylines with the per-feature columns of data, a dict or table, added or replaced.

with_units method descriptor 

with_units(units)

New polylines with the units of units, column name to unit; None removes one.

used in