{"id":19248581,"url":"https://github.com/nvidiagameworks/displacement-micromap-toolkit","last_synced_at":"2025-04-21T11:34:31.948Z","repository":{"id":148122496,"uuid":"606182931","full_name":"NVIDIAGameWorks/Displacement-MicroMap-Toolkit","owner":"NVIDIAGameWorks","description":null,"archived":false,"fork":false,"pushed_at":"2023-12-19T20:08:55.000Z","size":32160,"stargazers_count":121,"open_issues_count":2,"forks_count":10,"subscribers_count":23,"default_branch":"main","last_synced_at":"2024-05-03T14:41:30.536Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NVIDIAGameWorks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-02-24T19:42:25.000Z","updated_at":"2024-04-18T01:55:22.000Z","dependencies_parsed_at":"2023-12-20T12:02:58.538Z","dependency_job_id":null,"html_url":"https://github.com/NVIDIAGameWorks/Displacement-MicroMap-Toolkit","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIAGameWorks%2FDisplacement-MicroMap-Toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIAGameWorks%2FDisplacement-MicroMap-Toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIAGameWorks%2FDisplacement-MicroMap-Toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIAGameWorks%2FDisplacement-MicroMap-Toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NVIDIAGameWorks","download_url":"https://codeload.github.com/NVIDIAGameWorks/Displacement-MicroMap-Toolkit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223863920,"owners_count":17216234,"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":[],"created_at":"2024-11-09T18:09:06.079Z","updated_at":"2025-04-21T11:34:31.918Z","avatar_url":"https://github.com/NVIDIAGameWorks.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!IMPORTANT]\n\u003e This project has been archived and is no longer maintained. The vulkan\n\u003e extension `VK_NV_displacement_micromap` is no longer available.\n\u003e\n\u003e We recommend exploring [**NVIDIA RTX Mega\n\u003e Geometry**](https://developer.nvidia.com/blog/nvidia-rtx-mega-geometry-now-available-with-new-vulkan-samples/),\n\u003e which can provide similar functionality with greater flexibility. See\n\u003e [vk_tessellated_clusters](https://github.com/nvpro-samples/vk_tessellated_clusters),\n\u003e which demonstrates raytracing displacement with Vulkan.\n\n# NVIDIA Displacement Micro-Map Toolkit\n\nThis toolkit provides libraries, samples and tools to create and view displaced micromeshes.\nIt is a work in progress and feedback is welcome!\n\nThe latest driver exposing `VK_NV_displacement_micromap` is required to\nraytrace micromeshes, such as the *Vulkan Beta Driver* available at\nhttps://developer.nvidia.com/vulkan-driver.\n\nWe recommend to check the [Micro-Mesh Basics\nslides](https://developer.download.nvidia.com/ProGraphics/nvpro-samples/slides/Micro-Mesh_Basics.pdf)\nfirst as well as the [`dmm_displacement`\nmini-sample](/mini_samples/dmm_displacement/README.md).\n\nThere are also NVIDIA GTC presentations [Getting Started with Compressed Micro-Meshes \\[S51410\\]](https://register.nvidia.com/flow/nvidia/gtcspring2023/attendeeportal/page/sessioncatalog/session/1666430278669001BFSR)\n and [Interactive GPU-Based Remeshing of Large Meshes \\[S51567\\]](https://register.nvidia.com/flow/nvidia/gtcspring2023/attendeeportal/page/sessioncatalog/session/1666622202853001BIHK).\n\nThe NVIDIA Micro-Mesh technology covers both opacity micromaps and displacement micromaps.\nThis SDK currently solely covers displacements as a separate SDK exists for opacity.\n\n![](docs/micromesh_reefcrab.png)\n\n- [NVIDIA Displacement Micromap Toolkit](#nvidia-displacement-micromap-toolkit)\n  - [Building](#building)\n    - [Windows](#windows)\n    - [Linux](#linux)\n  - [Example Micromeshes](#example-micromeshes)\n  - [SDK and Toolkit Structure](#sdk-and-toolkit-structure)\n    - [**micromesh SDK**](#micromesh-sdk)\n    - [**bary file**](#bary-file)\n    - [**meshops API**](#meshops-api)\n    - [**tools \\\u0026 libraries**](#tools--libraries)\n    - [**mini samples**](#mini-samples)\n    - [**micromesh toolbox**](#micromesh-toolbox)\n    - [**micromesh tool**](#micromesh-tool)\n    - [**micromesh python**](#micromesh-python)\n  - [Fundamental Data Structures](#fundamental-data-structures)\n  - [Micromesh Asset Pipeline](#micromesh-asset-pipeline)\n  - [Third-Party Licenses](#third-party-licenses)\n\n## Building\n\nThis repository contains submodules. After cloning, initialize them with:\n\n```\ngit submodule update --init --recursive --jobs 8\n```\n\nThe one manual dependency is the [Vulkan SDK](https://vulkan.lunarg.com/). For\nWindows, make sure to install the optional \"glm\" during the install or set the\ncmake `GLM_INCLUDE_DIR` location if installed separately.\n\nFurther dependencies will be downloaded during the cmake configuration step.\n\n### Windows\n\nTested with Visual Studio 2017, 2019 and 2022. Use\n[cmake-gui](https://cmake.org/download/) to generate project files.\n\n- Install the [Vulkan SDK](https://vulkan.lunarg.com/) with **glm** (set\n  cmake `GLM_INCLUDE_DIR` if glm is installed separately)\n- Clone this repository and initialize the submodules\n- Run cmake-gui, source code = this repo, build folder = anywhere\n- Configure and Generate. Vulkan paths should be set by the SDK installer.\n- Open path\\\\to\\\\build\\\\micromesh_toolkit.sln with Visual Studio\n- In Solution Explorer, right click `micromesh_toolbox` and \"Set as Startup Project\"\n- Build -\u003e Build Solution\n\nSee [docs/examples.md](docs/examples.md) for usage examples.\n\n### Linux\n\nTested with gcc 11.2.1 and 11.3.0. This assumes build tools and cmake are\nalready installed.\n\n- Install the [Vulkan SDK](https://vulkan.lunarg.com/)\n- Install glm (e.g. `sudo apt install libglm-dev` or `sudo dnf install glm-devel`)\n- Install X11, GLFW and nVidia-ML libs\n  (`sudo apt-get install libx11-dev libxcb1-dev libxcb-keysyms1-dev libxcursor-dev libxi-dev libxinerama-dev libxrandr-dev \tlibxxf86vm-dev libvulkan-dev libglfw3-dev libnvidia-ml-dev` )\n- Clone this repository and initialize the submodules\n- Run `source path/to/vulkan-sdk/1.3..\u003cversion\u003e/setup-env.sh`\n- Run `cmake -DVULKAN_BUILD_DEPENDENCIES=on -S . -B path/to/build`\n- Run `make -C path/to/build -j`\n\nSee [docs/examples.md](docs/examples.md) for usage examples.\n\n## Example Micromeshes\n\nThe toolkit provides some basic tools to process and bake displacement\nmicromaps. Think of it like creating a heightmap to apply to a low-poly mesh,\nexcept the heightmap is highly compressed, supports hardware accelerated\nraytracing and doesn't need UVs. Some example starting assets are provided here\nto demonstrate toolkit usage. Download these to get started but feel free to try\nyour own.\n\n- [Crab](https://developer.download.nvidia.com/ProGraphics/nvpro-samples/reefcrab.7z)\n- [Wall](https://developer.download.nvidia.com/ProGraphics/nvpro-samples/wall.7z)\n- [Rocks](https://developer.download.nvidia.com/ProGraphics/nvpro-samples/rocks.7z)\n- [PingPongPaddle](https://developer.download.nvidia.com/ProGraphics/nvpro-samples/pingpongpaddle.7z)\n\nNote that these tools currently only support assets in glTF format. Everything\nelse must be converted.\n\nSee [docs/examples.md](docs/examples.md) for typical asset processing examples\nusing these meshes.\n\n## SDK and Toolkit Structure\n\n### **micromesh SDK**\n\nThe [NVIDIA Displacement Micro-Map SDK](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-SDK/)\nis the low-level API meant for embedding in other applications and tools.\nIt has a C-style API as well as an API agnostic GPU interface to facilitate this. \nAs a result it is sometimes a bit less easy to use. All functionality is provided\nthrough the `micromesh` namespace and it makes frequent use of the `micromesh::ArrayInfo`\nstructure, which allows it to pass data as a pointer \u0026 stride combination. All user visible data\nis allocated by the user, so some operations are executed in two steps where a *micromeshOpSomethingBegin* returns\nthe sizing required, while *micromeshOpSomethingEnd* completes it. One can also abort such \noperations with *micromeshOpContextAbort*. The `micromesh::Context` therefore is stateful\nbut fairly lightweight, in case you want to create one per thread. Right now there is also some rudimentary\nautomatic threading within the context.\n\n- [`micromesh_core`](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-SDK/micromesh_core/README.md):\n  Library for basic data structures, utilities and operations to create or\n  modify micromap and micromesh data.\n- [`micromesh_displacement_compression`](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-SDK/micromesh_displacement_compression/README.md):\n  Library that handles the compression of displacement micromaps.\n- [`micromesh_displacement_remeshing`](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-SDK/micromesh_displacement_remeshing/README.md):\n  Library for GPU-based remeshing.\n\n### **bary file**\n\n- [NVIDIA Displacement Micro-Map BaryFile](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-BaryFile/): library for the `.bary` file container that is used to store `micromaps`. The repository provides three libraries\n  - `bary_core`: The core library defines the structs used in the container and provides basic functions that aid validation and serialization. C-style interface.\n  - `bary_utils`: Utility library has C++ utilities that aid storing data with stl containers as well as loading or saving things via file operations.\n  - `bary_tool`: A command-line tool that prints key information about the content of `.bary` files.\n\n### **meshops API**\n\nThe `meshops` API is a layer above the `micromesh` SDK, that provides easier usage and higher level operations, \nsuch as baking. The functions typically operate on a single mesh provided in memory through an abstraction called `meshops::MeshView`. \nThis layer makes use of a Vulkan implementation for the various GPU-based operations and leverages\nthe `nvpro_core` framework doing so.\n\nThis `meshops` layer is still a bit work in progress as we are migrating additional capabilities to it and might see a few more changes than the `micromesh` API.\n\n- [`meshops_core`](/meshops_core/README.md): Provides the main framework for the `meshops` namespace\n  and covers several [basic operations](/meshops_core/include/meshops/meshops_operations.h)\n- [`meshops_bake`](/meshops_bake): Features a variety of operations based on raytracing from the base mesh to the high detail reference mesh.\n  We want to point out this is not a commercial class baker and it primarily exists for sample purposes.\n  - [`meshops_remesher`](/meshops_remesher): The remesher runs a novel\n    GPU-accelerated mesh simplification algorithm and also generates other mesh\n    properties useful for displacement micromap baking.\n  - generate displacement micromaps for high detail reference meshes, which optionally can be tessellated on the fly to account for additional heightmap displacement if provided.\n  - resample existing textures from the high detail reference mesh to the base mesh (also allows creation or resampling of tangent space normal maps).\n\n### **tools \u0026 libraries**\n\nAll tools operate on glTF 2.0 files and do support additional micromap specific\nglTF extensions from NVIDIA. The specifications are available at\n\u003chttps://github.com/KhronosGroup/glTF/pull/2273\u003e.\n\nAll micromap data is stored as `.bary` files which is a new container / file\nformat that was specifically designed to allow direct storage of data consumed\nby the raytracing APIs without additional processing. See the open-source\n[NVIDIA Displacement Micro-Map\nBaryFile](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-BaryFile/)\nfor more details. \n\n- [`micromesh_tool`](/micromesh_tool/README.md): This is the main tool for `meshops` based operation.\n  We intend to move all tooling operations here, but haven't completed this migration and refactoring yet.\n  The tool operations currently operate on an independent scene state (load gltf freshly), in future there will be a persistent in-memory scene that the\n  operations modify.\n  The tool currently supports:\n  - *baking* using `meshops_bake`\n  - *pre-tessellation* using `meshops_core`, compute subdivision levels and adjust base mesh tessellation to account for subdiv level 5 limit \n  - *displaced-tessellation* using `meshops_core`, create a tessellated mesh that applies all displacements provided through the micromaps (flatten the mesh to traditional triangles)\n  - *optimization*: trims and compresses micromeshes. Since only compressed micromaps are compatible with the ray tracing APIs, this can be used to prepare uncompressed micromaps for rendering.\n  - *remeshing* using `meshops_remesher`, decimates a mesh to be used as a base mesh for baking.\n- [`micromesh_python`](/micromesh_python): This is a python module with similar\n  functionality to `micromesh_tool`, exposing toolkit operations from the\n  `meshops_*` layer, but without the dependence on glTF. It operates on meshes\n  with geometry and other attributes defined by more generic `numpy` arrays.\"\n\n### **mini samples**\n  \nThe mini-samples showcase our APIs in a minimal fashion, not relying on loading models or other files, but just procedurally generating content to reduce the\namount of complexity\n\n- [`dmm_displacement`](/mini_samples/dmm_displacement/README.md): Learn how to raytrace displaced micromeshes \n  using the `VK_NV_displacement_micromap` extension. It also shows how to create the necessary data\n  for it in a minimal fashion using the `micromesh` sdk. \n  The extension support is mandatory for this sample.\n\n\u003e At the time of writing `VK_NV_displacement_micromap` is in beta still, meaning\n  the extension is subject to changes. Do not use its headers here in production\n  code!\n\n### **micromesh toolbox**\n\nThe [`micromesh_toolbox`](/micromesh_toolbox/README.md) is a graphical workbench\nthat allows inspecting micromeshes as well as interacting with some of the\ntools. It relies on `VK_NV_mesh_shader` to allow rasterized display of\nmicromeshes. `VK_KHR_acceleration_structure` is required for baking micromaps.\nIf available, `VK_NV_displacement_micromap` is used to render micromeshes with\nraytracing when choosing *Rendering -\u003e RTX*. `VK_NV_displacement_micromap` was\nintroduced with the RTX 40 Series Ada Lovelace architecture based GPUs. Previous\nRTX cards have support, but performance will be better with Ada. If you see a\nmessage about the missing extension, update to the latest driver (note: beta\ndrivers are available at https://developer.nvidia.com/vulkan-driver).\n\n\u003e The rasterization of micromeshes, especially compressed, is a bit of\n  a more complex topic on its own. A dedicated sample is available at\n  https://github.com/nvpro-samples/vk_displacement_micromaps.\n\n\u003e At the time of writing `VK_NV_displacement_micromap` is in beta still, meaning\n  the extension is subject to changes. Do not use its headers here in production\n  code!\n\n### **micromesh tool**\n\nThe command line tool, [`micromesh_tool`](/micromesh_tool/README.md), can be\nused for automation and defining persistent asset pipelines.\n\n### **micromesh python**\n\nThe python bindings for the toolkit, summarized in a [`Jupyter Notebook`](/micromesh_python/notebook/micromesh.ipynb), can be used for integrating asset pipelines inside any application supporting a Python environment.\n\nSee [`micromesh_python`](/micromesh_python/README.md) for more details.\n\n## Fundamental Data Structures\n\nA **micromesh** is the result of subdividing a base triangle using a power of two scheme.\nIt is made of **microtriangles** and **microvertices**.\n\n```\nTriangle W,U,V\n\n          V                     V                       V\n          x                     x                       x\n         / \\                   / \\ micro               / \\\n        /   \\                 /   \\ triangle          x _ x microvertex\n       /     \\               /     \\                 / \\ / \\\n      /       \\             x _____ x               x _ x _ x\n     /         \\           / \\     / \\             / \\ / \\ / \\\n    /           \\         /   \\   /   \\           x _ x _ x _ x\n   /             \\       /     \\ /     \\         / \\ / \\ / \\ / \\ \n  x _____________ x     x _____ x _____ x       x _ x _ x _ x _ x\nW                  U   W                  U   W                   U\n\nSubdivision level 0    Subdivision level 1    Subdivision level 2\n  1 microtriangle        4 microtriangles       16 microtriangles\n  aka base triangle\n```\n\nSee [docs/data_structures.md](docs/data_structures.md) for more details on how this is used to generate displacement.\n\n## Micromesh Asset Pipeline\n\nWe describe the core steps that would be performed to create a micromesh asset\nfrom an original input mesh in the [Micro-Mesh Asset Pipeline\nslide-deck](https://developer.download.nvidia.com/ProGraphics/nvpro-samples/slides/Micro-Mesh_Asset_Pipeline.pdf)\nas well as in [docs/asset_pipeline.md](docs/asset_pipeline.md)\n\n## About the Latest Release\n\nVersion 1.2\n\n- Add eR11_unorm_packed_align32 support in meshopsOpCompressDisplacementMicromaps()\n- Add micromesh_tool --normal-textures-stem to generate normal maps\n- The micromesh_tool --resample-resolution argument now takes a 2D resolution\n- Faceted shading option when raytracing, or when missing normal maps\n- Update to the latest nvpro_core\n- Use heightmap_rtx to preview heightmap displacement when raytracing\n- Write textures in parallel when saving scenes\n- Fix baking heightmaps from base mesh materials - now using reference mesh\n- Fix support for loading \\*.exr heightmaps\n- Filter outliers for dynamic range when using --height-textures-stem (experimental)\n- SW texture interpolation to preview heightmap displacement with rasterization\n\nVersion 1.1\n\n- Heightmap rendering in micromesh_toolkit with dynamic LOD\n- Memory estimate for baking high resolution heightmaps in batches\n- Micromesh USD schema definitions and libusd API\n- meshopsOpApplyBounds() to apply (and discard) direction bounds to positions and directions\n- Better glTF instancing/node hierarchy support for baking whole scenes\n- Fixes for image filename generation when resampling\n- Avoid leaving unused and empty glTF extension references\n- Fix matching regular texture names in automation/link_heightmaps.py\n\n## Third-Party Licenses\n\nThis project embeds or includes (as submodules) several third-party open-source\nlibraries and/or code derived from them. All such libraries' licenses are\nincluded in the PACKAGE-LICENSES folder of [this project](PACKAGE-LICENSES) or\nof the [nvpro_core\ndependency](https://github.com/nvpro-samples/nvpro_core/tree/master/PACKAGE-LICENSES).\n\n## Support Contact\n\nFeel free to file issues directly on the GitHub page or reach out to NVIDIA at\n\u003cdisplacedmicromesh-sdk-support@nvidia.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvidiagameworks%2Fdisplacement-micromap-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnvidiagameworks%2Fdisplacement-micromap-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvidiagameworks%2Fdisplacement-micromap-toolkit/lists"}