pylag.processing.release_zone module

A set of classes and functions to help with creating particle release zones.

class pylag.processing.release_zone.ReleaseZone(group_id: int | None = 1, radius: float | None = 100.0, centre=[0.0, 0.0], coordinate_system: str | None = 'cartesian', epsg_code: str | None = None)[source]

Bases: object

Release zone

A release zone is a circular region in cartesian space containing a set of particles.

Parameters:

  • group_id (int, optional) – Group ID associated with the release zone. Optional, defaults to 1.

  • radius (float, optional) – The radius of the release zone in m. Optional, defaults to 100.0 m.

  • centre (array_like, optional) – Two element array giving the coordinates of the centre of the release zone. Optional, defaults to [0.0, 0.0].

  • coordinate_system (str, optional) – Coordinate system used to interpret the given centre coordinates. The options are ‘geographic’ or ‘cartesian’ (default). If ‘geographic’ is given, the coordinates are assumed to be in lon/lat. If ‘cartesian’ is given, the coordinates are assumed to be in x/y.

  • epsg_code (str, optional) – EPSG code which should be used to covert to UTM coordiantes. If not given, the EPSG code will be inferred from centre. If working in cartesian coordinates, this argument is ignored.

add_particle(x, y, z)[source]

Add a particle to the release zone

Parameters:

  • x (float) – x-coordinate

  • y (float) – y-coordinate

  • z (float) – z-coordinate

Return type:

None

property area
property centre
property coordinate_system
create_particle_set(n_particles: int | None = 100, z: float | None = 0.0, random: bool | None = True)[source]

Create a new particle set

Create a new particle set (n=n_particles). The spatial coordinates of each particle are computed. If random is true, exactly n, random, uniformly distributed particles will be created. If false, particles are uniformly distributed on a cartesian grid, which is then filtered for the area encompassed by the release zone, which is determined from the radius. The latter algorithm yields a particle set with n <= n_particles where |n - n_particles| / n -> 1 for large n. The former guarantees that positions for exactly n particles are created. However, for small n the particle distribution with be patchy. All particles created are given the same depth coordinates.

Parameters:

  • n_particles (int, optional) – The number of particles to be created and added to the release zone. Defaults to 100.

  • z (float, optional) – The depth of the particles. Defaults to 0.0 m.

  • random (bool, optional) – If True (default) create particle positions at random. This guarantees that n_particles will be added to the release zone. If False, particles are regularly spaced on a Cartesian grid, which is then filtered for the area of the circle. Optional, defaults to True.

Return type:

N/A

property epsg_code
get_centre_utm_coordinates()[source]

Get UTM transformed centre coordinates

get_coordinates()[source]

Get particle coordinates

Returns:

  • array_like – Particle x-coordinates

  • array_like – Particle y-coordinates

  • array_like – Particle z-coordinates

get_number_of_particles()[source]

Get the total number of particles

Returns:

The total number of particles

Return type:

int

get_utm_coordinates()[source]

Get particle UTM coordinates

Return UTM coordiantes for all particles in the set. This method will raise an exception if the release zone is defined in cartesian coordinates. For release zones defined in geographic coordinates, convert these coordinates to UTM coordiantes and return. The returned coordinates are in the form (eastings, northings, depths). The EPSG code used to transform from geographic to UTM coordinates is also returned.

Parameters:

N/A

Returns:

  • eastings (array_like) – Eastings in m.

  • northings (array_like) – Northings in m.

  • depths (array_like) – Depths in m.

  • epsg_code (str) – EPSG code used to transform from geographic to UTM coordinates.

get_zone_polygon()[source]

Make a polygon of the points in the zone (based on its convex hull)

Returns:

poly – Polygon

Return type:

shapely.geometry.Polygon

property group_id
property particle_set
property radius
property x_coordinates
property y_coordinates
property z_coordinates
pylag.processing.release_zone.create_release_zone(group_id: int | None = 1, radius: float | None = 100.0, centre=[0.0, 0.0], coordinate_system: str | None = 'cartesian', epsg_code: str | None = None, n_particles: int | None = 100, depth: float | None = 0.0, random: bool | None = True) → ReleaseZone[source]

Create a new release zone

Parameters:

  • group_id (integer, optional) – Group identifier. Optional, defaults to 1.

  • radius (float, optional) – Radius of the circle in meters. Optional, defaults to 100.0 m.

  • centre (ndarray [float, float], optional) – x, y coordinates of the circle centre in meters. Optional, defaults to [0.0, 0.0].

  • coordinate_system (str, optional) – Coordinate system used to interpret the given centre coordinates. The options are ‘geographic’ or ‘cartesian’ (default). If ‘geographic’ is given, the coordinates are assumed to be in lon/lat. If ‘cartesian’ is given, the coordinates are assumed to be in x/y.

  • epsg_code (str, optional) – EPSG code which should be used to covert to UTM coordiantes. If not given, the EPSG code will be inferred from centre. If working in cartesian coordinates, this argument is ignored.

  • n_particles (integer, optional) – The number of particles. Optional, defaults to 100.

  • depth (float, optional) – Zone depth in m. Optional, defaults to 0.0 m.

  • random (boolean, optional) – Assign x/y positions randomly. Optional, defaults to True.

Returns:

release_zone – ReleaseZone object.

Return type:

ReleaseZone

pylag.processing.release_zone.create_release_zones_along_cord(start_point, end_point, coordinate_system: str | None = 'cartesian', epsg_code: str | None = None, group_id: int | None = 1, radius: float | None = 100.0, n_particles: int | None = 100, depth: float | None = 0.0, random: bool | None = True, verbose: bool | None = False) → list[source]

Generate a set of release zones along a cord

Return particle positions along a line r, defined by the position vectors start_point and end_point. start_point and end_point may be defined in Cartesian or geographic coordinates. Optionally, a epsg_code code can be provided. If provided, this will be used to convert geographic coordinates into UTM coordinates so distances can be calculated.Particles are packed into circlular zones of radius radius, running along r. Positions for approximately n particles (= n if random is True) are returned per zone. If 2*radius is > |r|, no zones are created.

Parameters:

  • start_point (array_like [float, float]) – Two component position vector in cartesian or geographic coordinates (x,y or lon/lat) that defines the start of the cord.

  • end_point (array_like [float, float]) – Two component position vector in cartesian coordinates or geographic coordinates (x,y or lon/lat) that defines the end of the cord.

  • coordinate_system (str, optional) – Coordinate system used to interpret the given r1 and r2 coordinates. The options are ‘geographic’ or ‘cartesian’.

  • epsg_code (str, optional) – EPSG code which should be used to covert to UTM coordiantes. If not given, the EPSG code will be inferred from start_point. If working in cartesian coordinates, this argument is ignored.

  • group_id (integer, optional) – Group id for the 1st release zone created along the cord.

  • radius (float, optional) – The radius of each zone m.

  • n_particles (integer, optional) – Number of particles per zone.

  • depth (float, optional) – Zone depth in m.

  • random (boolean, optional) – If true create a random uniform distribution of particles within each zone (default).

  • verbose (boolean, optional) – Hide warnings and progress details (default).

Returns:

zones – List of release zone objects along the cord.

Return type:

list

pylag.processing.release_zone.create_release_zones_around_shape(polygon: Polygon, start_point: Point, coordinate_system: str | None = 'cartesian', epsg_code: str | None = None, target_length: float | None = None, release_zone_radius: float | None = 100.0, n_particles: int | None = 100, group_id: int | None = 0, depth: float | None = 0.0, random: bool | None = True, check_overlaps: bool | None = False, overlap_tol: float | None = 0.0001, verbose: bool | None = False) → list[source]

Create a set of adjacent release zones around a shape

This function will create a set of release zones around the perimeter of a polygon. The release zones are created by stepping around the perimeter of the polygon, starting at the point start_point. start_point does not need to be exactly on the perimeter of the polygon - the method will find the nearest vertex and use this as the actual start point. The release zones are created such that they are adjacent to one another, and each release zone is given a unique groud ID.

The coordinates used to defined the polygon and the start point should be the same, and consistent with the coordinate_system argument. Valid options for coordinate_system are ‘geographic’ or ‘cartesian’. If ‘geographic’ is given, the coordinates are assumed to be in lon/lat. To compute distances, lon/lat coordinates are converted to UTM coordinates using the EPSG code given by epsg_code. If epsg_code is not given, the EPSG code is inferred from the start point coordinates. If ‘cartesian’ is given, the coordinates are assumed to be in x/y and not further coordinate transformations are performed.

The argument target_length can be used to specify the length of the polygon section around which release zones should be created. If None, the release zones will be created around the full perimeter of the polygon. The argument release_zone_radius specifies the radius of each release zone.

Parameters:

  • polygon (shapely.geometry.Polygon) – Polygon describing a given landmass or object. All points in lon/lat coordinates.

  • start_point (shapely.geometry.Point) – Approximate start point for release zones in lon/lat coordinates. The actual start point will be the nearest vertex on the polygon to the given coordinates.

  • coordinate_system (str, optional) – Coordinate system used to interpret the coordinates of the polygon and start_point objects. The options are ‘geographic’ or ‘cartesian’. Optional, defaults to ‘cartesian’.

  • epsg_code (str, optional) – EPSG code which should be used to covert to UTM coordiantes. If not given, the EPSG code will be inferred from start_point.

  • target_length (float, optional) – Distance along which to position release zones in m. Optional, defaults to None. If None, the release zones will be created around the full perimeter of the polygon.

  • release_zone_radius (float, optional) – Radius of each circular release zone in m. Optional, defaults to 100.0 m.

  • n_particles (integer, optional) – Number of particles per release zone. Optional, defaults to 100.

  • group_id (integer, optional) – ID of the first release zone created. All subsequent release zones will have an ID of group_id + 1, group_id + 2, etc. Optional, defaults to 0.

  • depth (float, optional) – Zone depth in m. Defaults to a depth of 0.0 m.

  • random (boolean, optional) – If true create a random uniform distribution of particles within each zone. Optional, defaults to True.

  • check_overlaps (boolean, optional) – If true check for overlaps between non-adjacent release zones that may result from jagged features. NOT YET IMPLEMENTED.

  • overlap_tol (float, optional) – Overlap tolerance. This can be increased to permit small overlaps between adjacent release zones. Optional, defaults to 0.0001.

  • verbose (boolean, optional) – Hide warnings and progress details. Optional, default False.

Returns:

release_zones – List of release zone objects.

Return type:

list

Todo

1) Allow users to provide a set of finish coordinates as an alternative to a length, which can then be used to determine the location of the last release zone to be created.