dased.layout¶

This module provides classes for managing DAS layouts in both local Cartesian and geographic coordinate systems.

Warning

DASLayoutGeographic is experimental and has not yet been tested thoroughly.

Classes¶

`DASLayout`	Represents a DAS cable layout defined by knot points, channel spacing and the choice of spline interpolation.
`DASLayoutGeographic`	Georeferenced DAS layout using local Cartesian coordinates with CRS transformation.

Descriptions¶

class dased.layout.DASLayout(knots=None, spacing=None, elevation=0, field_properties={}, signal_decay=0.0, wrap_around=False, anchors=None, **kwargs)¶

Represents a DAS cable layout defined by knot points, channel spacing and the choice of spline interpolation. Manages the positioning and properties of DAS channels along a cable path defined by knot points.

Parameters:

knots (ndarray) – A 2D array (N x 2) of local Cartesian coordinates defining the cable path knot points in meters. Minimum 2 points required.
spacing (float) – Spacing between channels along the cable in meters. Must be positive.
elevation (float | DataArray | Callable[[ndarray, ndarray], ndarray]) –
Elevation handling for the cable path. Can be:
- float: Constant elevation applied to all channels
- xarray.DataArray: Gridded elevation data from which elevation is interpolated
- callable: Function f(x, y) returning elevation at given coordinates
Defaults to 0.
field_properties (Dict[str, float | int | DataArray | Callable] | None) –
Dictionary containing additional field properties to interpolate along cable. Keys represent property names, values can be:
- Constants (float/int): Applied uniformly to all channels
- xarray.DataArray: Gridded data for spatial interpolation
- callable: Function f(x, y) for custom property calculation
Defaults to an empty dictionary (no additional properties).
signal_decay (float | None) –
Signal decay rate in dB/km for attenuation modeling. Used for modeling signal loss along the cable length.

If None or ≤0, signal strength remains constant.

Defaults to 0 (no decay modeling).
wrap_around (bool) – Whether to connect the last knot to the first to form a closed loop. Useful for creating circular or ring-shaped DAS arrays. Defaults to False.
**kwargs –
Additional arguments passed to scipy.interpolate.splprep for spline fitting. Common options:
- k: int, smoothing order (1=linear, 2=quadratic, 3=cubic)
- s: float, smoothing factor (0=exact interpolation)
- t: array-like, parameter values for knot otherwise calculated automatically from chord length

Examples

Basic straight-line layout:

>>> import numpy as np
>>> # Example knots as a NumPy array (2 x N coordinates in meters) :class:`~numpy.ndarray`
>>> knots = np.array([[0, 0], [1000, 0]])  # :class:`~numpy.ndarray`
>>> layout = DASLayout(knots, spacing=10.0)
>>> print(layout)

property channel_locations¶

Coordinates of channel locations along the cable. Channels are placed at equal arc-length intervals along the spline-interpolated cable path.

Returns:

Array of shape (N, 3) where N is the number of channels. Each row contains [x, y, z] coordinates in local Cartesian system.

x, y: Local horizontal coordinates
z: Elevation above reference datum

Return type:

ndarray

property channel_directions¶

Direction unit vectors for each channel along the cable, representing local cable orientation.

Returns:

Array of shape (N, 3) where N is the number of channels. Each row contains [u_x, u_y, u_z] unit direction vector.

u_x, u_y: Horizontal direction components
u_z: Vertical direction component (elevation gradient)

Return type:

ndarray

property channel_spacing¶

Spacing between channels along the cable.

Set during initialization and used throughout the spline stepping process to determine channel placement intervals. Actual spacing may vary slightly.

Final number of channels depends on total cable length divided by this spacing.

Returns:: Target channel spacing. Always positive.
Return type:: float

property n_channels¶

Number of channels placed along the cable.

Depends on the total cable length and the specified channel spacing. Channels are placed at (near) equal arc-length intervals starting from the beginning of the cable path.

Returns:: Number of channels. Always non-negative. Returns 0 if no valid cable path could be created.
Return type:: int

property cable_length¶

Total length of the cable path.

Calculated as the cumulative arc length along the spline-interpolated path between knot points. Accounts for both horizontal distance and elevation changes.

Returns:: Total cable length. Always non-negative.
Return type:: float

property knot_locations¶

Knot point coordinates used to define the cable path.

These are the processed knot points used for spline interpolation, which may differ from the input knots if wrap_around was enabled (adds duplicate of first point at end).

Returns:: Array of shape (M, 2) where M is the number of knot points. Each row contains [x, y] coordinates in local Cartesian system.
Return type:: ndarray

property anchor_locations¶: Backward compatibility alias for knot_locations.

Deprecated since version Use: knot_locations instead.

property field_properties¶

Dictionary of field properties associated with the cable layout.

Contains all field properties that can be interpolated at channel locations, including elevation data and any additional properties provided during initialization.

Returns:: Dictionary mapping property names (str) to their data. Always contains ‘elevation’ key. Additional keys depend on field_properties parameter passed to constructor.
Return type:: dict

Values can be:

Constants (float/int): Applied uniformly to all channels
xarray.DataArray: Gridded data for spatial interpolation
callable: Function f(x, y) for custom property calculation

property signal_decay¶

Signal decay rate for attenuation modeling in dB/km.

Used to model signal strength reduction along the cable length. When provided, signal strength decreases exponentially with distance from the cable start point.

Returns:: Signal decay rate in dB/km.
Return type:: float

get_array()¶

Return the layout data as a NumPy array.

Returns:

Combined array of shape (N, 6) containing:: [x, y, z, u_x, u_y, u_z] for each channel

Return type:

ndarray

get_shapely()¶

Return the layout cable path as a Shapely LineString object.

Returns:

LineString representation of the cable path: using 2D coordinates. Returns empty LineString if fewer than 2 channels.

Return type:

shapely.geometry.LineString

get_gdf()¶

Convert the layout to a GeoDataFrame with local coordinates.

Creates a GeoDataFrame containing channel information with Point geometries and comprehensive attributes including channel positions and directions, distance along cable from start, signal strength factors, and interpolated field properties.

Returns:

GeoDataFrame with the following columns:

channel_id: Sequential channel identifiers (0, 1, 2, …)

type: Receiver type (always “das”)

u_x, u_y, u_z: Direction vector components

distance: Distance along cable from start

signal_strength: Signal strength factor (1.0 = full strength)

geometry: Point geometries in local coordinates

z: Elevation values

Additional columns for each field property

Return type:

geopandas.GeoDataFrame

Notes

The GeoDataFrame uses local Cartesian coordinates with CRS=None. For georeferenced output, use get_gdf.

plot(ax=None, show_knots=False, knot_color='k', direction_scale=None, plot_style='channels', knot_kwargs=None, **kwargs)¶

Plot the DAS layout in a 2D top-down view using local coordinates.

Parameters:

ax – Matplotlib axes to plot on. If None, creates new figure and axes. Defaults to None.
show_knots – Whether to plot knot points. Defaults to False.
knot_color – Color for knot point markers. Defaults to “k” (black).
direction_scale – Scaling factor for channel direction arrows. If None, defaults to 80% of channel spacing. Defaults to None.
plot_style –
Visualization style. Can be:
- ”channels”: Plot as direction arrows showing channel orientations
- ”line”: Plot as connected line showing cable path
Defaults to “channels”.
knot_kwargs – Additional keyword arguments for knot point plotting (passed to ax.scatter). Defaults to None.
**kwargs – Additional keyword arguments passed to the primary plotting function (ax.quiver for “channels”, ax.plot for “line”).

Returns:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

Return type:

tuple

aperture()¶

Calculate the maximum distance between any two channels in the layout.

This represents the overall “aperture” or span of the DAS array, which is important for seismic analysis capabilities.

Returns:

Maximum distance between any pair of channels.: Returns 0.0 if there are fewer than 2 channels.

Return type:

float

translate(offset)¶

Translate the entire layout by a specified offset in local coordinates.

This method shifts all channel and knot locations by the given (dx, dy) offset, effectively moving the entire layout without altering its shape or orientation.

Parameters:: offset – Tuple or array-like of (dx, dy) translation in meters.
Raises:: ValueError – If offset is not a tuple or array-like of length 2.

copy()¶

Create a deep copy of the DASLayout instance.

Returns:: A new instance that is a deep copy of the current layout.
Return type:: DASLayout

class dased.layout.DASLayoutGeographic(knots=None, reference_point=None, crs=None, spacing=None, elevation=0, field_properties={}, signal_decay=None, wrap_around=False, t=None, anchors=None, **kwargs)¶

Georeferenced DAS layout using local Cartesian coordinates with CRS transformation.

This class extends DASLayout to support georeferenced DAS layouts by: 1. Performing channel calculations in a local Cartesian coordinate system 2. Using a reference point and CRS to provide geographic context 3. Handling coordinate transformation during data export

The local coordinate system origin (0,0) corresponds to the reference point in the specified CRS. This approach provides:

Computational efficiency (avoids complex geodesic calculations)
Numerical stability (avoids precision issues with large geographic coordinates)
Flexibility (supports both geographic and projected reference systems)

Parameters:

knots – 2D array (N x 2) of local Cartesian coordinates (x, y) in meters, relative to an origin (0,0).
reference_point – Coordinates (longitude, latitude) or (x, y) of the local origin (0,0) in the system defined by crs.
crs – The Coordinate Reference System of the reference_point and the target system for georeferencing.
spacing – Desired spacing between channels along the cable in meters.
elevation – Elevation data relative to the datum. If gridded or callable, it should expect local Cartesian coordinates (x, y). Defaults to 0.
field_properties –
Dictionary mapping property names to their data:
- Constants (float/int): Applied uniformly
- xr.DataArray: Gridded data for spatial interpolation
- callable: Function f(x,y) in local coordinate system
Properties should be defined in the local coordinate system. Defaults to None.
signal_decay – Signal decay rate in dB/km. If None or ≤0, signal strength remains constant (1.0). Defaults to None.
wrap_around – Whether to connect the last knot to the first to form a closed loop. Defaults to False.
t – Custom parameterization values for knot points controlling spline behavior. If None, calculated automatically from cumulative chord length. Defaults to None.
**kwargs – Additional arguments passed to scipy.interpolate.splprep for spline fitting.

Raises:

ValueError – If spacing is not positive, if knots are not a valid 2D array (N x 2), if CRS is invalid, or if reference_point is not a valid coordinate pair.

Coordinate System Handling:

Geographic CRS (e.g., EPSG:4326): The reference point represents
(longitude, latitude) and defines the center of a local Azimuthal Equidistant projection for internal calculations.
Projected CRS (e.g., UTM): The reference point represents (x, y)
coordinates within that projection, serving as an offset for the local coordinate system.

get_gdf(output_crs=None)¶

Return a GeoDataFrame with channel locations transformed to the specified CRS.

The transformation process depends on whether the primary CRS (self.crs) is geographic or projected:

If self.crs is geographic (e.g., EPSG:4326), the reference_point
(lon, lat) defines the center of a local Azimuthal Equidistant (AEQD) projection. Local Cartesian coordinates are transformed from this local AEQD system to the output_crs.
If self.crs is projected (e.g., UTM), the reference_point (x, y)
defines the origin offset within that projected system. Local Cartesian coordinates are translated by this offset within self.crs, and then potentially re-projected to output_crs.

Parameters:

output_crs – The target CRS for the output GeoDataFrame. If None, the CRS provided during initialization (self.crs) is used. Defaults to None.

Returns:

GeoDataFrame with channel points and attributes,: with geometry in the target CRS.

Return type:

geopandas.GeoDataFrame

plot(ax=None, plot_crs=None, use_basemap=False, basemap_provider=None, basemap_kwargs=None, plot_style='line', show_knots=True, knot_color='k', knot_kwargs=None, **kwargs)¶

Plot the DAS layout in geographic coordinates, optionally with a basemap.

Parameters:

ax – Matplotlib axes to plot on. If None, a new figure and axes are created. Defaults to None.
plot_crs – The CRS to use for plotting. If None, uses the layout’s native CRS (self.crs). If use_basemap is True, data will be projected to Web Mercator (EPSG:3857). Defaults to None.
use_basemap – Whether to add a contextual basemap using contextily. Requires contextily to be installed. Defaults to False.
basemap_provider – The basemap provider to use. See contextily documentation for options. Defaults to contextily’s default.
basemap_kwargs – Additional keyword arguments passed to contextily.add_basemap. Defaults to None.
plot_style –
How to represent the layout:
- ’line’: Plot the cable path as a line.
- ’points’: Plot individual channel locations as points.
- ’channels’: Plot channels with local direction arrows (use with caution
  in geographic plots as directions are not transformed).
Defaults to “line”.
show_knots – Whether to plot the knot points. Defaults to True.
knot_color – Color for the knot points. Defaults to “k”.
knot_kwargs – Additional keyword arguments passed to ax.scatter for plotting knots. Defaults to None.
**kwargs – Additional keyword arguments passed to the plotting function (gdf.plot for line/points, ax.quiver for channels).

Returns:

(matplotlib.figure.Figure, matplotlib.axes.Axes)

Return type:

tuple

Raises:

ImportError – If use_basemap is True and contextily is not installed.
ValueError – If an invalid plot_style is provided.