A wrapper for hmm
Project description
pydelatin
A Python wrapper of hmm
(of which Delatin is a port) for fast terrain mesh generation.
A screenshot of Glacier National Park taken from the demo. The mesh
is created using pydelatin
, encoded using
quantized-mesh-encoder
, served on-demand using
dem-tiler
, and rendered with deck.gl.
Install
With pip:
pip install pydelatin
or with Conda:
conda install -c conda-forge pydelatin
Binary wheels are provided for macOS and Linux. On Windows, glm
is a
prerequisite for building from source. Open an issue if you'd like to help
package binary wheels for Windows.
Using
Example
from pydelatin import Delatin
tin = Delatin(terrain, width, height)
# Mesh vertices
tin.vertices
# Mesh triangles
tin.triangles
API
The API is similar to that of hmm
.
Additionally I include a helper function: decode_ele
, to decode a Mapbox
Terrain RGB or Terrarium PNG array to elevations.
Delatin
Arguments
arr
(numpyndarray
): data array. If a 2D array, dimensions are expected to be (height, width). If a 1D array, height and width parameters must be passed, and the array is assumed to be in C order.height
(int
, default:None
): height of array; required when arr is not 2Dwidth
(int
, default:None
): width of array; required when arr is not 2Dz_scale
(float
, default:1
): z scale relative to x & yz_exag
(float
, default:1
): z exaggerationmax_error
(float
, default:0.001
): maximum triangulation errormax_triangles
(int
, default:None
): maximum number of trianglesmax_points
(int
, default:None
): maximum number of verticesbase_height
(float
, default:0
): solid base heightlevel
(bool
, default:False
): auto level input to full grayscale rangeinvert
(bool
, default:False
): invert heightmapblur
(int
, default:0
): gaussian blur sigmagamma
(float
, default:0
): gamma curve exponentborder_size
(int
, default:0
): border size in pixelsborder_height
(float
, default:1
): border z height
Attributes
vertices
(ndarray
of shape(-1, 3)
): the interleaved 3D coordinates of each vertex, e.g.[[x0, y0, z0], [x1, y1, z1], ...]
.triangles
(ndarray
of shape(-1, 3)
): represents indices within thevertices
array. So[0, 1, 3, ...]
would use the first, second, and fourth vertices within thevertices
array as a single triangle.error
(float
): the maximum error of the mesh.
util.rescale_positions
A helper function to rescale the vertices
output to a new bounding box.
Returns an ndarray
of shape (-1, 3)
with positions rescaled. Each row
represents a single 3D point.
Arguments
vertices
: (np.ndarray
) vertices output from Delatinbounds
: (Tuple[float]
) linearly rescale position values to this extent. Expected to be[minx, miny, maxx, maxy]
.flip_y
: (bool
, defaultFalse
) Flip y coordinates. Can be useful since images' coordinate origin is in the top left.
Saving to mesh formats
Quantized Mesh
A common mesh format for the web is the Quantized Mesh
format, which is supported in Cesium and deck.gl (via
loaders.gl). You can use
quantized-mesh-encoder
to save in this format:
import quantized_mesh_encoder
from pydelatin import Delatin
from pydelatin.util import rescale_positions
tin = Delatin(terrain, max_error=30)
vertices, triangles = tin.vertices, tin.triangles
# Rescale vertices linearly from pixel units to world coordinates
rescaled_vertices = rescale_positions(vertices, bounds)
with open('output.terrain', 'wb') as f:
quantized_mesh_encoder.encode(f, rescaled_vertices, triangles)
Meshio
Alternatively, you can save to a variety of mesh formats using
meshio
:
from pydelatin import Delatin
import meshio
tin = Delatin(terrain, max_error=30)
vertices, triangles = tin.vertices, tin.triangles
cells = [("triangle", triangles)]
mesh = meshio.Mesh(vertices, cells)
# Example output format
# Refer to meshio documentation
mesh.write('foo.vtk')
Martini
or Delatin
?
Two popular algorithms for terrain mesh generation are the "Martini"
algorithm, found in the JavaScript martini
library and the Python
pymartini
library, and the "Delatin" algorithm, found in the
C++ hmm
library, this Python pydelatin
library, and the JavaScript
delatin
library.
Which to use?
For most purposes, use pydelatin
over pymartini
. A good breakdown from a
Martini issue:
Martini:
- Only works on square 2^n+1 x 2^n+1 grids.
- Generates a hierarchy of meshes (pick arbitrary detail after a single run)
- Optimized for meshing speed rather than quality.
Delatin:
- Works on arbitrary raster grids.
- Generates a single mesh for a particular detail.
- Optimized for quality (as few triangles as possible for a given error).
Benchmark
The following uses the same dataset as the pymartini
benchmarks, a 512x512 pixel heightmap of Mt. Fuji.
For the 30-meter mesh, pydelatin
is 25% slower than pymartini
, but the mesh
is much more efficient: it has 40% fewer vertices and triangles.
pydelatin
is 4-5x faster than the JavaScript delatin
package.
Python
git clone https://github.com/kylebarron/pydelatin
cd pydelatin
pip install '.[test]'
python bench.py
mesh (max_error=30m): 27.322ms
vertices: 5668, triangles: 11140
mesh (max_error=1m): 282.946ms
mesh (max_error=2m): 215.839ms
mesh (max_error=3m): 163.424ms
mesh (max_error=4m): 127.203ms
mesh (max_error=5m): 106.596ms
mesh (max_error=6m): 91.868ms
mesh (max_error=7m): 82.572ms
mesh (max_error=8m): 74.335ms
mesh (max_error=9m): 65.893ms
mesh (max_error=10m): 60.999ms
mesh (max_error=11m): 55.213ms
mesh (max_error=12m): 54.475ms
mesh (max_error=13m): 48.662ms
mesh (max_error=14m): 47.029ms
mesh (max_error=15m): 44.517ms
mesh (max_error=16m): 42.059ms
mesh (max_error=17m): 39.699ms
mesh (max_error=18m): 37.657ms
mesh (max_error=19m): 36.333ms
mesh (max_error=20m): 34.131ms
JS (Node)
This benchmarks against the delatin
JavaScript module.
git clone https://github.com/kylebarron/pydelatin
cd test/bench_js/
yarn
wget https://raw.githubusercontent.com/mapbox/delatin/master/index.js
node -r esm bench.js
mesh (max_error=30m): 143.038ms
vertices: 5668
triangles: 11140
mesh (max_error=0m): 1169.226ms
mesh (max_error=1m): 917.290ms
mesh (max_error=2m): 629.776ms
mesh (max_error=3m): 476.958ms
mesh (max_error=4m): 352.907ms
mesh (max_error=5m): 290.946ms
mesh (max_error=6m): 240.556ms
mesh (max_error=7m): 234.181ms
mesh (max_error=8m): 188.273ms
mesh (max_error=9m): 162.743ms
mesh (max_error=10m): 145.734ms
mesh (max_error=11m): 130.119ms
mesh (max_error=12m): 119.865ms
mesh (max_error=13m): 114.645ms
mesh (max_error=14m): 101.390ms
mesh (max_error=15m): 100.065ms
mesh (max_error=16m): 96.247ms
mesh (max_error=17m): 89.508ms
mesh (max_error=18m): 85.754ms
mesh (max_error=19m): 79.838ms
mesh (max_error=20m): 75.607ms
License
This package wraps @fogleman's hmm
, a C++ library that is also
MIT-licensed.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for pydelatin-0.2.1-cp39-cp39-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 130f6fd9029df71b8bceb57709dcefa433b1bc80475ebe32d9d03026fe48a33a |
|
MD5 | f1172b36400c277009456d76e8fca428 |
|
BLAKE2b-256 | e3024e2a7bec30dc9272e9bb62bf8a069f565b8ae670a30ecf7b5b125d8f072c |
Hashes for pydelatin-0.2.1-cp39-cp39-manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e8721212332df78908307332b27173ce813150f83c7e3f4b75fa070321a9e17d |
|
MD5 | 9fb655109a2d58214fef2fb3aa19de3f |
|
BLAKE2b-256 | 0d32b414a2d9336c988a8b0b97d726743198f92e49ea4223d079136cd4ff1831 |
Hashes for pydelatin-0.2.1-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 517b2e1f192eaad10b99696dccbd95755452c14b39a388f946b35139870f6c9d |
|
MD5 | af7894b06ef031aea39bf5953baece6b |
|
BLAKE2b-256 | 542bdf11a2e70ca3358e34c443afbdfe65d6e6ef8c1738e8ba8ac65914526bea |
Hashes for pydelatin-0.2.1-cp38-cp38-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 79fd5e1a3af9562611213ab4aa4dd21d0b449881a1b73f2627e0d9679b7517cb |
|
MD5 | 7cb89ef018a4125d91bcb2e67f788785 |
|
BLAKE2b-256 | 23bdccad8d9755a74abadc523ddd9669606a1dd4ca7f6ee94080786425b558f8 |
Hashes for pydelatin-0.2.1-cp38-cp38-manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ba3667947b6586389de2e1df4ac5daba874468485e2bbbc73df7e566c75f66b3 |
|
MD5 | 5ce3e640ca20e1c772d3054ffc964dca |
|
BLAKE2b-256 | 5c2d144ce78513693a50a8644cdd75bf6226bd08af2ddbc2b634d19a2e3b75fc |
Hashes for pydelatin-0.2.1-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8afd77cb3f134ff006d3febc7400ad7f64d1f5c7d23b9d29b76ec74b2ea10da6 |
|
MD5 | bdd31aea85e2b4606ba1ebc8e0248213 |
|
BLAKE2b-256 | bf69bf7ac832a084804da1c8eed4db2163ab521ed17408986128807421fdde02 |
Hashes for pydelatin-0.2.1-cp37-cp37m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5ae5d7c1fbc8867a978360bfcaa339d3c8564212b5a7084813c7421c5a84932e |
|
MD5 | 5047d39f8d41734539afc8fe3f818167 |
|
BLAKE2b-256 | b6b86b3df388dd9a7684e13a6c6d90d5173c93c21cc31ce64e98a792cd3ef041 |
Hashes for pydelatin-0.2.1-cp37-cp37m-manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a491fc4a271de8eaf52a17593c961d6c0d18808a97f45986cba234c8449d3fe4 |
|
MD5 | 938b6295bf18d56edde44dcc0997c4e9 |
|
BLAKE2b-256 | 2d6d30ef935c3dab48af6b6b9ac0efcd5ac8ef1825ca8e92413f6d416a132093 |
Hashes for pydelatin-0.2.1-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8e370adf4dc40cae845fb85bf172597e98a8f06056efec77256be609290862ce |
|
MD5 | 249531ccb421d3a3f0c79dcf04121704 |
|
BLAKE2b-256 | 9de42243c8ae4ee38ac62acb2ca055573b527815fe912533fab741466dd96a95 |
Hashes for pydelatin-0.2.1-cp36-cp36m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4df433affd354b9f2dacf6e0f5a1570fe4db69dec3f3bb1046fa66e874844347 |
|
MD5 | d322bf9c530b32045664742cf1965f88 |
|
BLAKE2b-256 | 5f70d4cd4d3d6d4c37379b94929df78986ed88bbc7d7a4471ec287b6880363cb |
Hashes for pydelatin-0.2.1-cp36-cp36m-manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a6602686af0607839178c4bc97cd984c86e64289e0f99f218fdfa366064a412c |
|
MD5 | 0c9d454fbc92c18f942167d3b8232b0c |
|
BLAKE2b-256 | c84361e4a2ea78a4d4b8a234d5c5d41dbd6820111ec009b67f1ba70dd0e65952 |
Hashes for pydelatin-0.2.1-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e62c062129c535740a06831552f78f9402b65518625d4447a23906d971243e7c |
|
MD5 | 54681b1bc8582aed559ac2b31f2c3be9 |
|
BLAKE2b-256 | e858cb28043e6fce36372ccc49152c39ab8e644147936a2e34c9eb44c8fe0dc4 |