A fast Python Quantized Mesh encoder

These details have not been verified by PyPI

Project links

Homepage

Project description

quantized-mesh-encoder

A fast Python Quantized Mesh encoder. Encodes a mesh with 100k coordinates and 180k triangles in 20ms. Example viewer.

The Grand Canyon and Walhalla Plateau. The mesh is created using pydelatin or pymartini, encoded using quantized-mesh-encoder, served on-demand using dem-tiler, and rendered with deck.gl.

Overview

Quantized Mesh is a format to encode terrain meshes for efficient client-side terrain rendering. Such files are supported in Cesium and deck.gl.

This library is designed to support performant server-side on-demand terrain mesh generation.

Install

With pip:

pip install quantized-mesh-encoder

or with Conda:

conda install -c conda-forge quantized-mesh-encoder

Using

API

`quantized_mesh_encoder.encode`

Arguments:

f: a writable file-like object in which to write encoded bytes
positions: (array[float]): either a 1D Numpy array or a 2D Numpy array of shape (-1, 3) containing 3D positions.
indices (array[int]): either a 1D Numpy array or a 2D Numpy array of shape (-1, 3) indicating triples of coordinates from positions to make triangles. For example, if the first three values of indices are 0, 1, 2, then that defines a triangle formed by the first 9 values in positions, three for the first vertex (index 0), three for the second vertex, and three for the third vertex.

Keyword arguments:

bounds (List[float], optional): a list of bounds, [minx, miny, maxx, maxy]. By default, inferred as the minimum and maximum values of positions.
sphere_method (str, optional): As part of the header information when encoding Quantized Mesh, it's necessary to compute a bounding sphere, which contains all positions of the mesh. sphere_method designates the algorithm to use for creating the bounding sphere. Must be one of 'bounding_box', 'naive', 'ritter' or None. Default is None.
- 'bounding_box': Finds the bounding box of all positions, then defines the center of the sphere as the center of the bounding box, and defines the radius as the distance back to the corner. This method produces the largest bounding sphere, but is the fastest: roughly 70 µs on my computer.
- 'naive': Finds the bounding box of all positions, then defines the center of the sphere as the center of the bounding box. It then checks the distance to every other point and defines the radius as the maximum of these distances. This method will produce a slightly smaller bounding sphere than the bounding_box method when points are not in the 3D corners. This is the next fastest at roughly 160 µs on my computer.
- 'ritter': Implements the Ritter Method for bounding spheres. It first finds the center of the longest span, then checks every point for containment, enlarging the sphere if necessary. This can produce smaller bounding spheres than the naive method, but it does not always, so often both are run, see next option. This is the slowest method, at roughly 300 µs on my computer.
- None: Runs both the naive and the ritter methods, then returns the smaller of the two. Since this runs both algorithms, it takes around 500 µs on my computer
ellipsoid (quantized_mesh_encoder.Ellipsoid, optional): ellipsoid defined by its semi-major a and semi-minor b axes. Default: WGS84 ellipsoid.
extensions: list of extensions to encode in quantized mesh object. These must be Extension instances. See Quantized Mesh Extensions.

`quantized_mesh_encoder.Ellipsoid`

Ellipsoid used for mesh calculations.

Arguments:

a (float): semi-major axis
b (float): semi-minor axis

`quantized_mesh_encoder.WGS84`

Default WGS84 ellipsoid. Has a semi-major axis a of 6378137.0 meters and semi-minor axis b of 6356752.3142451793 meters.

Quantized Mesh Extensions

There are a variety of extensions to the Quantized Mesh spec.

`quantized_mesh_encoder.VertexNormalsExtension`

Implements the Terrain Lighting extension. Per-vertex normals will be generated from your mesh data.

Keyword Arguments:

indices: mesh indices
positions: mesh positions
ellipsoid: instance of Ellipsoid class, default: WGS84 ellipsoid

`quantized_mesh_encoder.WaterMaskExtension`

Implements the Water Mask extension.

Keyword Arguments:

data (Union[np.ndarray, np.uint8, int]): Data for water mask.

`quantized_mesh_encoder.MetadataExtension`

Implements the Metadata extension.

data (Union[Dict, bytes]): Metadata data to encode. If a dictionary, json.dumps will be called to create bytes in UTF-8 encoding.

Examples

Write to file

from quantized_mesh_encoder import encode
with open('output.terrain', 'wb') as f:
    encode(f, positions, indices)

Quantized mesh files are usually saved gzipped. An easy way to create a gzipped file is to use gzip.open:

import gzip
from quantized_mesh_encoder import encode
with gzip.open('output.terrain', 'wb') as f:
    encode(f, positions, indices)

Write to buffer

It's also pretty simple to write to an in-memory buffer instead of a file

from io import BytesIO
from quantized_mesh_encoder import encode
with BytesIO() as bio:
    encode(bio, positions, indices)

Or to gzip the in-memory buffer:

import gzip
from io import BytesIO
with BytesIO() as bio:
    with gzip.open(bio, 'wb') as gzipf:
        encode(gzipf, positions, indices)

Alternate Ellipsoid

By default, the WGS84 ellipsoid is used for all calculations. An alternate ellipsoid may be useful for non-Earth planetary bodies.

from quantized_mesh_encoder import encode, Ellipsoid

# From https://ui.adsabs.harvard.edu/abs/2010EM%26P..106....1A/abstract
mars_ellipsoid = Ellipsoid(3_395_428, 3_377_678)

with open('output.terrain', 'wb') as f:
    encode(f, positions, indices, ellipsoid=mars_ellipsoid)

Quantized Mesh Extensions

from quantized_mesh_encoder import encode, VertexNormalsExtension, MetadataExtension

vertex_normals = VertexNormalsExtension(positions=positions, indices=indices)
metadata = MetadataExtension(data={'hello': 'world'})

with open('output.terrain', 'wb') as f:
    encode(f, positions, indices, extensions=(vertex_normals, metadata))

Generating the mesh

To encode a mesh into a quantized mesh file, you first need a mesh! This project was designed to be used with pydelatin or pymartini, fast elevation heightmap to terrain mesh generators.

import quantized_mesh_encoder
from imageio import imread
from pymartini import decode_ele, Martini, rescale_positions
import mercantile

png = imread(png_path)
terrain = decode_ele(png, 'terrarium')
terrain = terrain.T
martini = Martini(png.shape[0] + 1)
tile = martini.create_tile(terrain)
vertices, triangles = tile.get_mesh(10)

# Use mercantile to find the bounds in WGS84 of this tile
bounds = mercantile.bounds(mercantile.Tile(x, y, z))

# Rescale positions to WGS84
rescaled = rescale_positions(
    vertices,
    terrain,
    bounds=bounds,
    flip_y=True
)

with BytesIO() as f:
    quantized_mesh_encoder.encode(f, rescaled, triangles)
    f.seek(0)
    return ("OK", "application/vnd.quantized-mesh", f.read())

You can also look at the source of _mesh() in dem-tiler for a working reference.

License

Much of this code is ported or derived from quantized-mesh-tile in some way. quantized-mesh-tile is also released under the MIT license.

Project details

These details have not been verified by PyPI

Project links

Homepage

Release history Release notifications | RSS feed

0.4.3

Nov 18, 2022

0.4.2

Dec 5, 2021

This version

0.4.1

Aug 9, 2021

0.4.0

Aug 9, 2021

0.3.1

Oct 19, 2020

0.3.0

Oct 12, 2020

0.2.2

Jul 10, 2020

0.2.1

Jul 10, 2020

0.2.0

Jul 1, 2020

0.1.2

Jun 1, 2020

0.1.0

May 31, 2020

0.0.1

May 29, 2020

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quantized-mesh-encoder-0.4.1.tar.gz (135.9 kB view details)

Uploaded Aug 9, 2021 Source

Built Distributions

quantized_mesh_encoder-0.4.1-cp310-cp310-win_amd64.whl (206.7 kB view details)

Uploaded Dec 5, 2021 CPython 3.10 Windows x86-64

quantized_mesh_encoder-0.4.1-cp310-cp310-musllinux_1_1_x86_64.whl (538.1 kB view details)

Uploaded Dec 5, 2021 CPython 3.10 musllinux: musl 1.1+ x86-64

quantized_mesh_encoder-0.4.1-cp310-cp310-musllinux_1_1_i686.whl (517.8 kB view details)

Uploaded Dec 5, 2021 CPython 3.10 musllinux: musl 1.1+ i686

quantized_mesh_encoder-0.4.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (534.0 kB view details)

Uploaded Dec 5, 2021 CPython 3.10 manylinux: glibc 2.17+ x86-64

quantized_mesh_encoder-0.4.1-cp310-cp310-macosx_11_0_arm64.whl (198.9 kB view details)

Uploaded Dec 5, 2021 CPython 3.10 macOS 11.0+ ARM64

quantized_mesh_encoder-0.4.1-cp310-cp310-macosx_10_9_x86_64.whl (206.8 kB view details)

Uploaded Dec 5, 2021 CPython 3.10 macOS 10.9+ x86-64

quantized_mesh_encoder-0.4.1-cp310-cp310-macosx_10_9_universal2.whl (269.8 kB view details)

Uploaded Dec 5, 2021 CPython 3.10 macOS 10.9+ universal2 (ARM64, x86-64)

quantized_mesh_encoder-0.4.1-cp39-cp39-win_amd64.whl (206.6 kB view details)

Uploaded Aug 9, 2021 CPython 3.9 Windows x86-64

quantized_mesh_encoder-0.4.1-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (498.8 kB view details)

Uploaded Aug 9, 2021 CPython 3.9 manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

quantized_mesh_encoder-0.4.1-cp39-cp39-macosx_11_0_arm64.whl (198.9 kB view details)

Uploaded Aug 9, 2021 CPython 3.9 macOS 11.0+ ARM64

quantized_mesh_encoder-0.4.1-cp39-cp39-macosx_10_9_x86_64.whl (206.8 kB view details)

Uploaded Aug 9, 2021 CPython 3.9 macOS 10.9+ x86-64

quantized_mesh_encoder-0.4.1-cp39-cp39-macosx_10_9_universal2.whl (269.7 kB view details)

Uploaded Aug 9, 2021 CPython 3.9 macOS 10.9+ universal2 (ARM64, x86-64)

quantized_mesh_encoder-0.4.1-cp38-cp38-win_amd64.whl (206.5 kB view details)

Uploaded Aug 9, 2021 CPython 3.8 Windows x86-64

quantized_mesh_encoder-0.4.1-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (509.7 kB view details)

Uploaded Aug 9, 2021 CPython 3.8 manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

quantized_mesh_encoder-0.4.1-cp38-cp38-macosx_11_0_arm64.whl (197.3 kB view details)

Uploaded Aug 9, 2021 CPython 3.8 macOS 11.0+ ARM64

quantized_mesh_encoder-0.4.1-cp38-cp38-macosx_10_9_x86_64.whl (204.7 kB view details)

Uploaded Aug 9, 2021 CPython 3.8 macOS 10.9+ x86-64

quantized_mesh_encoder-0.4.1-cp38-cp38-macosx_10_9_universal2.whl (266.1 kB view details)

Uploaded Aug 9, 2021 CPython 3.8 macOS 10.9+ universal2 (ARM64, x86-64)

quantized_mesh_encoder-0.4.1-cp37-cp37m-win_amd64.whl (205.7 kB view details)

Uploaded Aug 9, 2021 CPython 3.7m Windows x86-64

quantized_mesh_encoder-0.4.1-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (473.4 kB view details)

Uploaded Aug 9, 2021 CPython 3.7m manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

quantized_mesh_encoder-0.4.1-cp37-cp37m-macosx_10_9_x86_64.whl (205.2 kB view details)

Uploaded Aug 9, 2021 CPython 3.7m macOS 10.9+ x86-64

quantized_mesh_encoder-0.4.1-cp36-cp36m-win_amd64.whl (204.6 kB view details)

Uploaded Aug 9, 2021 CPython 3.6m Windows x86-64

quantized_mesh_encoder-0.4.1-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (472.3 kB view details)

Uploaded Aug 9, 2021 CPython 3.6m manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

quantized_mesh_encoder-0.4.1-cp36-cp36m-macosx_10_9_x86_64.whl (203.7 kB view details)

Uploaded Aug 9, 2021 CPython 3.6m macOS 10.9+ x86-64

File details

Details for the file quantized-mesh-encoder-0.4.1.tar.gz.

File metadata

Download URL: quantized-mesh-encoder-0.4.1.tar.gz
Upload date: Aug 9, 2021
Size: 135.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.4.2 importlib_metadata/4.6.3 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.0 CPython/3.9.6

File hashes

Hashes for quantized-mesh-encoder-0.4.1.tar.gz
Algorithm	Hash digest
SHA256	`4e1f3ccd7360762eaa3ca6ac208899df31fefb3f410113327b3d0b33469e2899`
MD5	`d8e6f7bbe182f7d7c029203b04a4a2c8`
BLAKE2b-256	`31f743fe484fc24f553db18de560c33b0bc25473ed66fdc28d6481151467eefa`

Algorithm	Hash digest
SHA256	`de4744edd4b7c0e1e5514a9927b0f65548180dac49140b9762018d71482803cf`
MD5	`a9976bfe09288ca59347f849fab806ca`
BLAKE2b-256	`536e9cb02cf9192e2fb878e9ed70631451700b273004f55b4f3fc64670dc1a12`

Algorithm	Hash digest
SHA256	`5131f4b5491a56bd7b157bc54eb19231047c4535c08856742d69da11b8a725d9`
MD5	`da6143ad88058fe7af20c5b4dfed8c2c`
BLAKE2b-256	`73f6217182e6c3a1b3003bed1645375d1b480098c9f8e001ca9c8dc97f72585a`

Algorithm	Hash digest
SHA256	`a90ea68d1e8498bea17c9adcd182b68fa8eaa7b68330a12b4549d6e41946c1dc`
MD5	`7bbd8687e445b0c1921af750785a594e`
BLAKE2b-256	`ac9ba672cb3348f55c64bac32c82d416639b1d4f4cd695c219cc030659cfbce5`

Algorithm	Hash digest
SHA256	`1aed1ee0f2d16fb842c0ed3eb294ecc123fe16c42e4b08cc3ee6636b4deca3cb`
MD5	`144bc842519d7be8716d0ee75a9dfb62`
BLAKE2b-256	`073c5e3abee2b354044fd41e05f7a8a243136001c41d0837f5047888697e1e71`

Algorithm	Hash digest
SHA256	`b1278ce06306e3699aef66c1bdcf91b1898b43ea191c37e6582bfee8cc2b9978`
MD5	`fa4accbe3428382f0139babbbf9e5bbd`
BLAKE2b-256	`48bdf64441f1ef7bda8038a8ea6061256b6ed0916dfb659e50ffbe9465cc406c`

Algorithm	Hash digest
SHA256	`1bc13b6bd87143f6f70c45bea43673a7d516735835c7e1addb85d802ecea76bd`
MD5	`cf04190ec5a4ccb32e1e062aed614051`
BLAKE2b-256	`c0ef0dca17dc42e0a1bbc1daf8f67910d2e0f7ea41a92363ce52cf972615c246`

Algorithm	Hash digest
SHA256	`594b2454519d348c525b0599e144b7c05fd691fa377421d7ec63edd5d4ff4452`
MD5	`93f48898cc1270286078657a10d57c2b`
BLAKE2b-256	`07ae2517141f6e5ea744340523c558429a16b442db5c941cdd4fe96286c747a7`

Algorithm	Hash digest
SHA256	`1178d36cae3bc144b41f8b460f9c0459e3d5c51e7efd258d0a843a88e9e9549f`
MD5	`719efcfee31c82ec522817ee545d8dd7`
BLAKE2b-256	`e9a2a3ea1d1e57bbb9d97a25f71b4884c4e4a898c83a6f834af5f658306cbbb9`

Algorithm	Hash digest
SHA256	`889d64e89fc1059ac0204d5bf4d6bde16c189b213339f5995c1ebe63636ed372`
MD5	`2599692607579b563ee1144c1ed1a940`
BLAKE2b-256	`92fc8b18ab12821343f306ca128c840ed35bd6b3845dadb07a98e93eb59983bd`

Algorithm	Hash digest
SHA256	`8beb0d282a0a72d7b29ce21c675e77a1bc7552a84a27242b17f70e620b6a0e5f`
MD5	`6a54a14095220e62cc44e6c216b51450`
BLAKE2b-256	`d6665f720f3e47e2ab84d4f13df3f92e1ba29f547c50201d1cc5203ed5b75301`

Algorithm	Hash digest
SHA256	`973e6f87a15ddddba471aff1c645e05842206bd1098656e60a9dc9a573896a0d`
MD5	`33ddd56e7e5d621f78d9bbb732a72e2d`
BLAKE2b-256	`f0abe0c43b317af15fcf2d1de120c1bf63cb6f11e910467d68e7ddbe329481f0`

Algorithm	Hash digest
SHA256	`ce13a669e7b6dee91a61337805036ac74dc0470984262d0a67b5c22a5f95fa6d`
MD5	`8d52be0882712e81d32d0ee7cac34c8b`
BLAKE2b-256	`4288e316606034297a144876f40097e7b41d5babf5fe57ac4432df079e86c44a`

Algorithm	Hash digest
SHA256	`0f2e913e71c3eac7e4f202a56915131c5e022e781bb4241e944ab5f7cc6b5aee`
MD5	`65a6e2e44e837e91105554a9c63e2557`
BLAKE2b-256	`201194c075e3558541b47041cf30e50edc813fbfdf6cb4c6870c26e284c8fd82`

Algorithm	Hash digest
SHA256	`a01ba29929836b8dac246deab2510268dc6ef9f01d1e84be02cee9abe50fc501`
MD5	`460429bcdc16169e25fc2467776da0a8`
BLAKE2b-256	`2494f2e00ae0ad9be654bba4752bdeb6724eb5b8f46f1a70470a797771e90eaa`

Algorithm	Hash digest
SHA256	`dba8461b8c738ef5e012941b7c8ee08aaf991627a8f507f15f40adb2fd72e8da`
MD5	`a6ec33c4afc5260e449e0c985f37587f`
BLAKE2b-256	`6e85b192727c06221c59c2938b216fbe78e50c460622bd648cecdfbd866b21c7`

Algorithm	Hash digest
SHA256	`250078b8d9e6510e732f8365449e9243fed5b6ee75914c2a3fc5e8318f085767`
MD5	`ef4c06aacb537dbe1c3e43c9b74807c9`
BLAKE2b-256	`d00a1b6ed060c62d90a925f7a16606e1a810f82ca79b9df859325306c2636b37`

Algorithm	Hash digest
SHA256	`025c6105957c4304381c8246846736cd0d79605e9f131c522aeae8ab9a38812a`
MD5	`2b6c624f735762569e5dfc60e76f4ee3`
BLAKE2b-256	`ce13eab723d6f45c336e77b193de75697385507a27b25c7adb76ec5aceeda65b`

Algorithm	Hash digest
SHA256	`e6d81cb4a61563b6a1d69045850e96b068e23dd1faef33f11fb51e413ae06e79`
MD5	`6ef73eb93e2a9a347968f32347f1997d`
BLAKE2b-256	`d2c5ab90c2295b4f7a055b2e03dd34cbf1936a7ed50379c7430961316a22935d`

Algorithm	Hash digest
SHA256	`913c56d8a01c450514d1295b4dc58ce72b3bc3709dabe8ab48f3e08b7c4d02ab`
MD5	`ffc264bc8433734d9fd4ba1f10b3c9e9`
BLAKE2b-256	`0acd47c8a15d8e742b3a33490448c11afd143deab74756c64d0771e54a5d3e84`

Algorithm	Hash digest
SHA256	`31a05f603ba36ec0e67014128fee618d060c57781f8c6024d22a20fdb3699c59`
MD5	`e221d97edfcd15e09ce1451ad7137a4c`
BLAKE2b-256	`ac923513cb3a4dcb10331dd6b5eddee585551a7eaa13f5c48938ad9612c6f5e7`

quantized-mesh-encoder 0.4.1

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

quantized-mesh-encoder

Overview

Install

Using

API

quantized_mesh_encoder.encode

quantized_mesh_encoder.Ellipsoid

quantized_mesh_encoder.WGS84

Quantized Mesh Extensions

quantized_mesh_encoder.VertexNormalsExtension

quantized_mesh_encoder.WaterMaskExtension

quantized_mesh_encoder.MetadataExtension

Examples

Write to file

Write to buffer

Alternate Ellipsoid

Quantized Mesh Extensions

Generating the mesh

License

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

`quantized_mesh_encoder.encode`

`quantized_mesh_encoder.Ellipsoid`

`quantized_mesh_encoder.WGS84`

`quantized_mesh_encoder.VertexNormalsExtension`

`quantized_mesh_encoder.WaterMaskExtension`

`quantized_mesh_encoder.MetadataExtension`

Algorithm	Hash digest
SHA256	`9f7a91db9839f23685ae62c804e6dbfd9d149773ed70f57a728af93c18a9c4f9`
MD5	`ef86fbc893dc4eeaa6f655eed8ec2f43`
BLAKE2b-256	`4c8c730709e6472840c1920fb618b04aaf1b3abc13dfbc6945e958dafcf9323e`

Algorithm	Hash digest
SHA256	`9804f8890b37d4af36fff2fd51893613a07f9d18cd03e297ce65b294ceae24f4`
MD5	`d8c07b9d6da00afb8c27a50dde3e6949`
BLAKE2b-256	`6d35b0ab13f5a52eebdfa21c630ea937b07d9978032cedcfcf846c8dcb0120e6`

Algorithm	Hash digest
SHA256	`b0a2cef680474c60ebb8b8d4ea6b6ca1980f5c419b73d9a4a22d689912ccc915`
MD5	`1fd8e767cdd7a477c1634cbac971a6f7`
BLAKE2b-256	`5b24941d527563f75e67ed5b1cc0b640c3bd401b5a4d468cc499c48aa3eabf22`