{"id":13678941,"url":"https://github.com/kylebarron/quantized-mesh-encoder","last_synced_at":"2025-07-04T10:33:35.042Z","repository":{"id":39088241,"uuid":"267773718","full_name":"kylebarron/quantized-mesh-encoder","owner":"kylebarron","description":"A fast Python Quantized Mesh encoder","archived":false,"fork":false,"pushed_at":"2023-03-07T14:22:57.000Z","size":6651,"stargazers_count":91,"open_issues_count":17,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-25T12:55:20.434Z","etag":null,"topics":["cesium","deck-gl","mesh","mesh-processing","quantized-mesh","terrain","terrain-mesh-generator"],"latest_commit_sha":null,"homepage":"https://kylebarron.dev/quantized-mesh-encoder","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kylebarron.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-05-29T05:34:23.000Z","updated_at":"2025-04-16T15:17:38.000Z","dependencies_parsed_at":"2024-01-14T15:24:13.242Z","dependency_job_id":"dc5ba062-facf-4136-bff2-6862b4c8fb00","html_url":"https://github.com/kylebarron/quantized-mesh-encoder","commit_stats":{"total_commits":161,"total_committers":6,"mean_commits":"26.833333333333332","dds":0.1925465838509317,"last_synced_commit":"0812c1830fd3aefe2e6ca27bf15b7bfe6cb5f8a0"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebarron%2Fquantized-mesh-encoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebarron%2Fquantized-mesh-encoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebarron%2Fquantized-mesh-encoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebarron%2Fquantized-mesh-encoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kylebarron","download_url":"https://codeload.github.com/kylebarron/quantized-mesh-encoder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250822433,"owners_count":21492904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cesium","deck-gl","mesh","mesh-processing","quantized-mesh","terrain","terrain-mesh-generator"],"created_at":"2024-08-02T13:01:00.061Z","updated_at":"2025-04-30T12:43:33.520Z","avatar_url":"https://github.com/kylebarron.png","language":"Python","funding_links":[],"categories":["Terrain"],"sub_categories":[],"readme":"# quantized-mesh-encoder\n\n[![Build Status](https://travis-ci.org/kylebarron/quantized-mesh-encoder.svg?branch=master)](https://travis-ci.org/kylebarron/quantized-mesh-encoder)\n\nA fast Python [Quantized Mesh][quantized_mesh_spec] encoder. Encodes a mesh with\n100k coordinates and 180k triangles in 20ms. [Example viewer][example].\n\n[![][image_url]][example]\n\n[image_url]: https://raw.githubusercontent.com/kylebarron/quantized-mesh-encoder/master/assets/no-texture-example.jpg\n[example]: https://kylebarron.dev/quantized-mesh-encoder\n\nThe Grand Canyon and Walhalla Plateau. The mesh is created using\n[`pydelatin`][pydelatin] or [`pymartini`][pymartini], encoded using\n`quantized-mesh-encoder`, served on-demand using [`dem-tiler`][dem-tiler], and\nrendered with [deck.gl](https://deck.gl).\n\n[pymartini]: https://github.com/kylebarron/pymartini\n[pydelatin]: https://github.com/kylebarron/pydelatin\n[dem-tiler]: https://github.com/kylebarron/dem-tiler\n\n## Overview\n\n[Quantized Mesh][quantized_mesh_spec] is a format to encode terrain meshes for\nefficient client-side terrain rendering. Such files are supported in\n[Cesium][cesium] and [deck.gl][deck.gl].\n\nThis library is designed to support performant server-side on-demand terrain\nmesh generation.\n\n[quantized_mesh_spec]: https://github.com/CesiumGS/quantized-mesh\n[cesium]: https://github.com/CesiumGS/cesium\n[deck.gl]: https://deck.gl/\n\n## Install\n\nWith pip:\n\n```\npip install quantized-mesh-encoder\n```\n\nor with Conda:\n\n```\nconda install -c conda-forge quantized-mesh-encoder\n```\n\n## Using\n\n### API\n\n#### `quantized_mesh_encoder.encode`\n\nArguments:\n\n- `f`: a writable file-like object in which to write encoded bytes\n- `positions`: (`array[float]`): either a 1D Numpy array or a 2D Numpy array of\n  shape `(-1, 3)` containing 3D positions.\n- `indices` (`array[int]`): either a 1D Numpy array or a 2D Numpy array of shape\n  `(-1, 3)` indicating triples of coordinates from `positions` to make\n  triangles. For example, if the first three values of `indices` are `0`, `1`,\n  `2`, then that defines a triangle formed by the first 9 values in `positions`,\n  three for the first vertex (index `0`), three for the second vertex, and three\n  for the third vertex.\n\nKeyword arguments:\n\n- `bounds` (`List[float]`, optional): a list of bounds, `[minx, miny, maxx,\n  maxy]`. By default, inferred as the minimum and maximum values of `positions`.\n- `sphere_method` (`str`, optional): As part of the header information when\n  encoding Quantized Mesh, it's necessary to compute a [_bounding\n  sphere_][bounding_sphere], which contains all positions of the mesh.\n  `sphere_method` designates the algorithm to use for creating the bounding\n  sphere. Must be one of `'bounding_box'`, `'naive'`, `'ritter'` or `None`.\n  Default is `None`.\n    - `'bounding_box'`: Finds the bounding box of all positions, then defines\n      the center of the sphere as the center of the bounding box, and defines\n      the radius as the distance back to the corner. This method produces the\n      largest bounding sphere, but is the fastest: roughly 70 µs on my computer.\n    - `'naive'`: Finds the bounding box of all positions, then defines the\n      center of the sphere as the center of the bounding box. It then checks the\n      distance to every other point and defines the radius as the maximum of\n      these distances. This method will produce a slightly smaller bounding\n      sphere than the `bounding_box` method when points are not in the 3D\n      corners. This is the next fastest at roughly 160 µs on my computer.\n    - `'ritter'`: Implements the Ritter Method for bounding spheres. It first\n      finds the center of the longest span, then checks every point for\n      containment, enlarging the sphere if necessary. This _can_ produce smaller\n      bounding spheres than the naive method, but it does not always, so often\n      both are run, see next option. This is the slowest method, at roughly 300\n      µs on my computer.\n    - `None`: Runs both the naive and the ritter methods, then returns the\n      smaller of the two. Since this runs both algorithms, it takes around 500\n      µs on my computer\n- `ellipsoid` (`quantized_mesh_encoder.Ellipsoid`, optional): ellipsoid defined by its semi-major `a`\n   and semi-minor `b` axes.\n   Default: WGS84 ellipsoid.\n- extensions: list of extensions to encode in quantized mesh object. These must be `Extension` instances. See [Quantized Mesh Extensions](#quantized-mesh-extensions).\n\n\n[bounding_sphere]: https://en.wikipedia.org/wiki/Bounding_sphere\n\n#### `quantized_mesh_encoder.Ellipsoid`\n\nEllipsoid used for mesh calculations.\n\nArguments:\n\n- `a` (`float`): semi-major axis\n- `b` (`float`): semi-minor axis\n\n#### `quantized_mesh_encoder.WGS84`\n\nDefault [WGS84 ellipsoid](https://en.wikipedia.org/wiki/World_Geodetic_System#1984_version). Has a semi-major axis `a` of 6378137.0 meters and semi-minor axis `b` of 6356752.3142451793 meters.\n\n#### Quantized Mesh Extensions\n\nThere are a variety of [extensions](https://github.com/CesiumGS/quantized-mesh#extensions) to the Quantized Mesh spec.\n\n##### `quantized_mesh_encoder.VertexNormalsExtension`\n\nImplements the [Terrain Lighting](https://github.com/CesiumGS/quantized-mesh#terrain-lighting) extension. Per-vertex normals will be generated from your mesh data.\n\nKeyword Arguments:\n\n- `indices`: mesh indices\n- `positions`: mesh positions\n- `ellipsoid`: instance of Ellipsoid class, default: WGS84 ellipsoid\n\n##### `quantized_mesh_encoder.WaterMaskExtension`\n\nImplements the [Water Mask](https://github.com/CesiumGS/quantized-mesh#water-mask) extension.\n\nKeyword Arguments:\n\n- `data` (`Union[np.ndarray, np.uint8, int]`): Data for water mask.\n\n##### `quantized_mesh_encoder.MetadataExtension`\n\nImplements the [Metadata](https://github.com/CesiumGS/quantized-mesh#metadata) extension.\n\n- `data` (`Union[Dict, bytes]`): Metadata data to encode. If a dictionary, `json.dumps` will be called to create bytes in UTF-8 encoding.\n\n### Examples\n\n#### Write to file\n\n```py\nfrom quantized_mesh_encoder import encode\nwith open('output.terrain', 'wb') as f:\n    encode(f, positions, indices)\n```\n\nQuantized mesh files are usually saved gzipped. An easy way to create a gzipped\nfile is to use `gzip.open`:\n\n```py\nimport gzip\nfrom quantized_mesh_encoder import encode\nwith gzip.open('output.terrain', 'wb') as f:\n    encode(f, positions, indices)\n```\n\n#### Write to buffer\n\nIt's also pretty simple to write to an in-memory buffer instead of a file\n\n```py\nfrom io import BytesIO\nfrom quantized_mesh_encoder import encode\nwith BytesIO() as bio:\n    encode(bio, positions, indices)\n```\n\nOr to gzip the in-memory buffer:\n\n```py\nimport gzip\nfrom io import BytesIO\nwith BytesIO() as bio:\n    with gzip.open(bio, 'wb') as gzipf:\n        encode(gzipf, positions, indices)\n```\n\n\n#### Alternate Ellipsoid\n\nBy default, the [WGS84\nellipsoid](https://en.wikipedia.org/wiki/World_Geodetic_System#1984_version) is\nused for all calculations. An alternate ellipsoid may be useful for non-Earth\nplanetary bodies.\n\n```py\nfrom quantized_mesh_encoder import encode, Ellipsoid\n\n# From https://ui.adsabs.harvard.edu/abs/2010EM%26P..106....1A/abstract\nmars_ellipsoid = Ellipsoid(3_395_428, 3_377_678)\n\nwith open('output.terrain', 'wb') as f:\n    encode(f, positions, indices, ellipsoid=mars_ellipsoid)\n```\n\n#### Quantized Mesh Extensions\n\n```py\nfrom quantized_mesh_encoder import encode, VertexNormalsExtension, MetadataExtension\n\nvertex_normals = VertexNormalsExtension(positions=positions, indices=indices)\nmetadata = MetadataExtension(data={'hello': 'world'})\n\nwith open('output.terrain', 'wb') as f:\n    encode(f, positions, indices, extensions=(vertex_normals, metadata))\n```\n\n#### Generating the mesh\n\nTo encode a mesh into a quantized mesh file, you first need a mesh! This project\nwas designed to be used with [`pydelatin`][pydelatin] or\n[`pymartini`][pymartini], fast elevation heightmap to terrain mesh generators.\n\n```py\nimport quantized_mesh_encoder\nfrom imageio import imread\nfrom pymartini import decode_ele, Martini, rescale_positions\nimport mercantile\n\npng = imread(png_path)\nterrain = decode_ele(png, 'terrarium')\nterrain = terrain.T\nmartini = Martini(png.shape[0] + 1)\ntile = martini.create_tile(terrain)\nvertices, triangles = tile.get_mesh(10)\n\n# Use mercantile to find the bounds in WGS84 of this tile\nbounds = mercantile.bounds(mercantile.Tile(x, y, z))\n\n# Rescale positions to WGS84\nrescaled = rescale_positions(\n    vertices,\n    terrain,\n    bounds=bounds,\n    flip_y=True\n)\n\nwith BytesIO() as f:\n    quantized_mesh_encoder.encode(f, rescaled, triangles)\n    f.seek(0)\n    return (\"OK\", \"application/vnd.quantized-mesh\", f.read())\n```\n\nYou can also look at the source of\n[`_mesh()`](https://github.com/kylebarron/dem-tiler/blob/5b50a216a014eb32febee84fe3063ca99e71c7f6/dem_tiler/handlers/app.py#L234)\nin [`dem-tiler`][dem-tiler] for a working reference.\n\n## License\n\nMuch of this code is ported or derived from\n[`quantized-mesh-tile`][quantized-mesh-tile] in some way. `quantized-mesh-tile`\nis also released under the MIT license.\n\n[pymartini]: https://github.com/kylebarron/pymartini\n[quantized-mesh-tile]: https://github.com/loicgasser/quantized-mesh-tile\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylebarron%2Fquantized-mesh-encoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkylebarron%2Fquantized-mesh-encoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylebarron%2Fquantized-mesh-encoder/lists"}