API documentation¶
startinpy does not have specific classes and/or objects for points, vertices, and triangles. NumPy arrays of floats and integers are used.
A Point is an array of 3 floats (x-coordinate, y-coordinate, z-coordinate):
>>> import startinpy
>>> dt = startinpy.DT()
>>> dt.insert_one_pt(11.3, 22.2, 4.7)
>>> dt.points[1]
array([11.3, 22.2, 4.7])
A Vertex is an integer, it is the index in the array of points (startinpy.DT.points(), which is 0-based).
A Triangle is an array of 3 integer, the values of the indices of the 3 vertices (ordered counter-clockwise) in the array of points (startinpy.DT.points(), which is 0-based).
>>> dt.triangles[2]
array([1, 3, 2], dtype=uint64)
>>> #-- z-coordinate of 3rd vertex of the same triangle
>>> dt.points[dt.triangles[2][2]][2]
3.3
Important
The first vertex in the list of points is the infinite vertex, and has no coordinates (it has this: [-99999.99999, -99999.99999, -99999.99999]). It is used internally to ensure that the whole DT is consistent. No Triangle refers to the vertex.
- class startinpy.DT¶
A Delaunay triangulation (DT), containing vertices+triangles
- adjacent_vertices_to_vertex(vi)¶
Return an array of vertex indices that are adjacent to vertex vi, that is those on the edges incident to vi. An exception is thrown if vi does not exist in the DT.
- Parameters
vi – the vertex index
- Returns
an array of vertex indices (ordered counter-clockwise)
- closest_point(x, y)¶
Return the closest vertex index to [x, y] (distance in 2D). An Exception is thrown if [x, y] is outside the convex hull.
- Parameters
x – the x-coordinate
y – the y-coordinate
- Returns
the vertex index of the closest point
>>> try: >>> cp = dt.closest_point(32.1, 66.9) >>> except Exception as e: >>> print(e)
- collect_garbage()¶
Collect garbage, that is remove from memory (the Vec of stars) the vertices marked as removed.
Watch out: the vertices get new IDs (and thus the triangles) too. And this can be a slow operation.
>>> if dt.has_garbage(): >>> dt.collect_garbage() >>> assert dt.has_garbage() == False
- convex_hull()¶
Return the convex hull as an array of vertex indices.
- Returns
an array of vertex indices, oriented counter-clockwise (CCW)
- get_bbox()¶
Return the bbox of the dataset
- Returns
an array of 4 coordinates: [minx, miny, maxx, maxy]
>>> bbox = dt.get_bbox() [ 505043.690 5258283.953 523361.172 5275100.003 ]
- get_point(vi)¶
Return the point for the vertex with index vi. An exception is thrown if vertex index is invalid.
- Parameters
vi – the index of the vertex
- Returns
the point
>>> v = dt.get_point(4) [13.0, 2.0, 11.11]
- has_garbage(factor)¶
Returns true if some vertices are marked as to be deleted (but still in memory) , false otherwise.
- Returns
true/false
- incident_triangles_to_vertex(vi)¶
Return the triangles incident to vertex vi. Exception thrown if vertex index doesn’t exist in the DT.
- Parameters
vi – the vertex index
- Returns
an array of triangles (ordered counter-clockwise)
>>> tri = dt.incident_triangles_to_vertex(3) >>> for i, dt in enumerate(tri): >>> print(i, t) 0 [3, 4, 6] 1 [3, 6, 7] 2 [3, 7, 8] 3 [3, 8, 2] 4 [3, 2, 9] 5 [3, 9, 4]
- insert(pts, *, insertionstrategy='AsIs')¶
Insert each point in the array of points (a 2D array) by calling insert_one_pt() for each. Different insertion strategies can be used: “AsIs” (default: inserts points in the order given) or “BBox” (inserts first the BBox of the points, which speeds up the construction, works especially good for rasters).
- Parameters
pts – an array of points (which is an array)
insertionstrategy (optional) – “AsIs” (default) or “BBox”
- Returns
(nothing)
>>> pts = [] >>> pts.append([1.0, 1.0, 11.11]) >>> pts.append([1.0, 2.3, 22.22]) >>> pts.append([12.3, 21.0, 4.52]) >>> ... >>> dt = startinpy.DT() >>> dt.insert(pts) OR >>> dt.insert(pts, insertionstrategy="BBox")
- insert_one_pt(x, y, z)¶
Insert one new point in the DT. If there is a point at the same location (based on
startinpy.DT.snap_tolerance()), then the point is not inserted and the index of the already existing vertex is returned.- Parameters
x – x-coordinate of point to insert
y – y-coordinate of point to insert
z – z-coordinate of point to insert
- Returns
index of the vertex in the DT
>>> dt.insert_one_pt(3.2, 1.1, 17.0) 5 (the vertex index in the DT is 5)
- interpolate_laplace(x, y)¶
Interpolation method: Laplace interpolation (details about the method). This is a variation of natural interpolation method with distances used instead of stolen areas. Thus faster in practice. An Exception is thrown if [x, y] is outside the convex hull.
- Parameters
x – the x-coordinate
y – the y-coordinate
- Returns
the estimated value
>>> try: >>> zhat = dt.interpolate_laplace(55.2, 33.1) >>> print("result: ", zhat) >>> except Exception as e: >>> print(e) 64.08234343
- interpolate_nn(x, y)¶
Interpolation method: nearest neighbour (or closest neighbour). An Exception is thrown if [x, y] is outside the convex hull.
- Parameters
x – the x-coordinate
y – the y-coordinate
- Returns
the estimated value
- interpolate_nni(x, y)¶
Interpolation method: natural neighbour method (also called Sibson’s method). An Exception is thrown if [x, y] is outside the convex hull.
- Parameters
x – the x-coordinate
y – the y-coordinate
- Returns
the estimated value
>>> try: >>> zhat = dt.interpolate_laplace(55.2, 33.1) >>> print("result: ", zhat) >>> except Exception as e: >>> print(e) 64.08234343
- interpolate_tin_linear(x, y)¶
Interpolation method: linear interpolation in TIN. An Exception is thrown if [x, y] is outside the convex hull.
- Parameters
x – the x-coordinate
y – the y-coordinate
- Returns
the estimated value
- is_inside_convex_hull(x, y)¶
Is the point [x, y] located inside the convex hull of the DT.
- Parameters
x – the x-coordinate
y – the y-coordinate
- Returns
True if [x,y] is inside the convex hull or on its boundary, False otherwise.
- is_triangle(t)¶
Verify if a triangle exists in the DT.
- Parameters
t – the triangle, an array of 3 vertex indices
- Returns
True if t exists, False otherwise.
>>> re = dt.is_triangle(np.array([11, 162, 666])))
- is_vertex_convex_hull(vi)¶
Return True if vertex vi is on the boundary of the convex hull, False otherwise.
- Parameters
vi – the vertex index
- Returns
True if vi is on the boundary of the convex hull, False otherwise. Also False is returned if the vertex doesn’t exist in the DT.
- locate(x, y)¶
Locate the triangle containing the point [x, y] (projected to 2D). An error is thrown if it is outside the convex hull.
- Parameters
x – the x-coordinate
y – the y-coordinate
- Returns
the triangle.
- number_of_triangles()¶
- Returns
number of (finite) triangles
- number_of_vertices()¶
- Returns
number of (finite) vertices
- points¶
Get the points [x, y, z] of all vertices in the DT. This includes the infinite vertex (vertex at position 0), which is not part of the DT. It has dummy coordinates and no triangles refer to it.
>>> pts = dt.points >>> print(pts.shape) (102, 3) #-- this is a numpy array >>> for p in pts: >>> print(p[0], p[1], p[2]) ... >>> dt.points[27] [101.122 72.293 11.223] >>> dt.points[0] [-99999.99999 -99999.99999 -99999.99999]
- read_las(path, *, classification=None, thinning=1)¶
Read the LAS/LAZ file and insert all the points in the DT.
- Parameters
path – full path (a string) on disk of the file to read
classification (optional) – a list of class(es) to keep. If not used then all points are inserted.
thinning (optional) – the thinning factor, eg 10 will randomly pick 1/10 points from the file.
- Returns
throws an exception if the path is invalid
>>> dt = startinpy.DT() >>> dt.read_las("/home/elvis/myfile.laz") >>> OR >>> dt.read_las("/home/elvis/myfile.laz", classification=[2,6]) >>> OR >>> dt.read_las("/home/elvis/myfile.laz", thinning=10, classification=[2,6])
- remove(vi)¶
Remove/delete the vertex vi (an index) from the DT, and update the DT for the Delaunay criterion.
- Parameters
vi – index of vertex to delete
- Returns
(Exception is thrown if vi is invalid)
>>> try: >>> t.remove(45) >>> except Exception as e: >>> print(e)
- snap_tolerance¶
Get/set the snap tolerance used to merge vertices during insertion. Two vertices closer than this will be the merged during insertion. (default=0.001)
>>> dt = startinpy.DT() >>> dt.snap_tolerance = 0.05 #-- modify to 0.05unit >>> print("The snap tolerance is:", dt.snap_tolerance) The snap tolerance is: 0.05
- triangles¶
Get the triangles in the DT.
>>> trs = dt.triangles >>> print(trs.shape) (224, 3) #-- this is a numpy array >>> one_triangle = trs[22] >>> first_vertex = one_triangle[0] >>> print("x-coordinate of first vertex: ", dt.points[first_vertex]) x-coordinate of first vertex: [25.98 35.12 4.78]
- vertical_exaggeration(factor)¶
Vertically exaggerate the elevation values of the vertices. Used mostly for visualisation.
- Parameters
factor – a positive value (can be <1.0 to remove exaggeration)
- Returns
(nothing)
>>> dt.vertical_exaggeration(2.0) >>> dt.vertical_exaggeration(0.5)
- write_geojson(path)¶
Write a GeoJSON file of the DT (vertices+triangles) to the path (a string). Throws an exception if the path is invalid.
- Parameters
path – full path (a string) on disk of the file to create (will overwrite)
- Returns
(nothing)
>>> dt.write_obj("/home/elvis/myfile.geojson")
- write_obj(path)¶
Write an OBJ of the DT to the path (a string). Throws an exception if the path is invalid.
- Parameters
path – full path (a string) on disk of the file to create (will overwrite)
- Returns
(nothing)
>>> dt.write_obj("/home/elvis/myfile.obj")
- write_ply(path)¶
Write an PLY of the DT to the path (a string). Throws an exception if the path is invalid.
- Parameters
path – full path (a string) on disk of the file to create (will overwrite)
- Returns
(nothing)
>>> dt.write_ply("/home/elvis/myfile.ply")