micromesh_python/notebook/micromesh.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5825ec8c-794a-4684-a8ea-f4e683ffdfc4",
   "metadata": {},
   "source": [
    "# NVIDIA Displacement Micromap Python Toolkit\n",
    "\n",
    "This notebook reviews the Micromap Python Toolkit.  It first reviews what Micromap data is, summarizes its use-cases in rendering, and gives a hands on introduction to the module.  The tutorial loads mesh data stored in the Universal Scene Description (USD) format, converts it to Numpy arrays and Python objects suitable for the Python module, and demonstrates how to use the toolkit to generate compressed displacement micromap data given high and low resolution meshes, including an optional heightmap.  It also demonstrates how to resample the input textures suitable to the UV-space of the displaced geometry.\n",
    "\n",
    "<center><img src=\"crab.jpg\"></img></center>\n",
    "\n",
    "### Prerequisites\n",
    "\n",
    "This notebook was developed and tested using USD 22.11, however it uses only minimal USD so you may be able to use similar versions.  You will need to install a version of Pixar USD by running the cell below, or you can download your own and add it to the Python path for the environment you're running this Jupyter notebook from.  Some pre-built binaries are made available here (https://developer.nvidia.com/usd#bin).  numpy and numba are also required for performant tweaking of attributes, and py7zr for extracting the downloaded notebook assets.  The following cell can uninstall these libraries if/when necessary.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "04bb56be-38ab-4c4e-aadd-6f8886e83b20",
   "metadata": {},
   "outputs": [],
   "source": [
    "#import sys\n",
    "#!{sys.executable} -m pip install usd-core==22.11 numpy numba py7zr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3941db21-5cd7-4338-84a3-0eb8f83d143e",
   "metadata": {},
   "outputs": [],
   "source": [
    "#!{sys.executable} -m pip uninstall usd-core numpy numba py7zr"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1bf8f7d1-457b-4fce-905a-bf571087814b",
   "metadata": {},
   "source": [
    "Download and extract the notebook assets:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bc02ad9e-3eed-4e88-af1b-0871e6453b5e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from utils.assets import fetch_and_extract\n",
    "\n",
    "remote_file = 'https://developer.download.nvidia.com/ProGraphics/nvpro-samples/notebook_assets.7z'\n",
    "\n",
    "fetch_and_extract(remote_file, '.', './assets', force=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8bfbe518-0db7-4a7a-b61b-98beed898251",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Micro-Mesh Overview\n",
    "\n",
    "Before jumping into the Displacement Micromap Python Toolkit, lets briefly review what micro-mesh technology is and how we can create it from our assets.  For a more detailed description, refer to (https://github.com/NVIDIAGameWorks/Displacement-MicroMap-SDK).  Micro-meshes with micromap data are an optimized and compressed set of geometry and at-runtime displacement and allow for reduced framebuffer requirements for high-resolution, displaced meshes.  Micro-meshes also enable faster bounding volume heirarchy (BVH) build and traversal times.  It comes with a trade-off in that while the BVH is quicker to build and traverse and requires less memory than a standard BVH and high-resolution mesh, there is a performance overhead when ray tracing as each ray trace into the leaf will incur a penalty to decode and intersect.  This will be discussed a bit more after describing the data.\n",
    "\n",
    "In a nutshell, displaced micromap data is a compressed representation of high-resolution geometric details coupled with a low-resolution triangle mesh -- similar to a texture but instead of sampled in UV-space the displacements are uniformly sampled on a barycentric grid within each base triangle.  This data is created by <i>baking</i> a high-resolution mesh or tesselated heightmap surface onto the low-resolution mesh and storing displacement values at <i>interpolated positions</i> within each triangle of the low-resolution mesh.  During the baking process, rays are traced from these interpolated positions to their intersection with the high-resolution mesh.  This distance determines their <i>displacement value</i> and when displaced the <i>micro-vertex position</i>.  Per-vertex <i>direction vectors</i> are interpolated across the low-resolution triangle using barycentric coordinates to become the <i>interpolated displacement vector</i>. These direction vectors could simply be vertex normals, or otherwise non-normalized custom vectors supplied by the user.  In the end, these direction vectors form a hull of varying thickness around the base mesh, and it is within this hull that all displacements occur. As such, this hull can be used as a quick measure of rendering efficiency -- the tighter the hull fits to the mesh, the faster potential displaced microtriangles can be ignored by the ray tracing hardware. In addition, a tighter hull allows for more resolution in the compressed displacements.\n",
    "\n",
    "Micro-vertex attribute interpolation, e.g. for positions or direction vectors, relies on the barycentric coordinates to place the micro-mesh displacements evenly across these base triangles, so as you may have guessed, isotropic triangles are much preferred in order to maximize resources. Triangles that are flat or elongated are still functional, they just overdefine the displacements and are not preferred.  As such, care should be taken when authoring the high-resolution meshes to avoid them.  Or, when applicable, a remeshing algorithm that can retriangluate the mesh to isotropic triangles that uniformly represent the displacement frequency in the high-resolution mesh can be used to generate the low-resolution mesh.\n",
    "\n",
    "<center><img src=\"microdisplacement.png\"></img></center>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c9e44ec-0b1a-4268-b3ba-15770e70822e",
   "metadata": {},
   "source": [
    "<a id=\"toc\"></a>\n",
    "## Displacement Micromap Python Toolkit\n",
    "\n",
    "The Python Toolkit presented here is a higher-level encapsulation of the Displacement Micromap SDK and related toolkits: \n",
    "* [Displacement-MicroMap-SDK](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-SDK)\n",
    "   * Low-level C-style API for creating, compressing, and optimizing micromap data\n",
    "   * Built upon Vulkan SDK for GPU accelerated ray tracing used when generating displacements\n",
    "   * Intended for tight integration into applications and tools utilizing C/C++\n",
    "* [Displacement-MicroMap-Toolkit](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-Toolkit)\n",
    "   * Higher-level suite of applications for creating, compressing, and optimizing micromap data from .gltf-formatted data\n",
    "   * Includes support for remeshing and pre-tessellation of meshes to support more efficient micromeshes\n",
    "   * Can be integrated into asset pipelines that support .gltf \n",
    "* [Displacement-MicroMap-BaryFile](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-BaryFile)\n",
    "   * .bary file format and container used to store micromesh-related attributes to disk\n",
    "   * .gltf extension that adds support for .bary to .gltf files\n",
    "* [NVIDIA Micro-Mesh Technology Landing Page](https://developer.nvidia.com/rtx/ray-tracing/micro-mesh)\n",
    "   * More information and links related to displaced micro-mesh and opacity micro-maps\n",
    "\n",
    "The Python Toolkit is intended an an entry point into the NVIDIA Displacement Micromap SDK for integration into DCC apps and in-house tools that leverage Python.  It exposes similar features as the Displacement Micromap Toolkit does for command line / pipelined assets but instead inside a Python environment.\n",
    "\n",
    "The Displacement Micromap Python Toolkit currently supports a number of workflows:\n",
    "\n",
    "1) [Baking Micro-Mesh Data](#baking_micromesh_data)\n",
    "   * [Settings](#baker_settings)\n",
    "   * [Texture Resampling](#texture_resampling)\n",
    "   * [Heightmaps](#heightmaps)\n",
    "   * [Baking](#baking)\n",
    "   * [Saving to .bary File Format](#save_to_bary)\n",
    "   * [Restoring from .bary File Format](#restore_from_bary)\n",
    "   * [Saving to USD](#save_to_usd)\n",
    "2) [Displaced Mesh Generation](#displaced_mesh)\n",
    "3) [Remeshing](#remeshing)\n",
    "4) [Pre-tessellating](#pretessellation)\n",
    "\n",
    "The rest of the notebook will introduce each workflow and how the Displacement Micromap Python Toolkit can be used to accomplish them."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7abd25cc-f94f-4800-828f-02cccb445287",
   "metadata": {},
   "source": [
    "## Baking Micro-Mesh Data<a id=\"baking_micromesh_data\"></a>\n",
    "\n",
    "Baking always requires a low-resolution or target mesh on which to place the displacements.  For the source surface, you can either use a high-resolution mesh, a low-resolution mesh with a heightmap, or both a high-resolution mesh and a heightmap.  In case with a heightmap, it will be applied to the mesh during the baking process in order to construct the final high-resolution surface.\n",
    "\n",
    "Before we can create any displacements we need to load the source data.  The next cell loads the given .usd stage into memory and briefly examines its contents."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9c565f8e-b75f-472a-8511-40bd7171c897",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from utils import mesh\n",
    "from pxr import Usd, UsdGeom\n",
    "\n",
    "stage = Usd.Stage.Open('./assets/simplewall/simplewall.usd')\n",
    "\n",
    "for prim in stage.Traverse():\n",
    "    if prim.IsA(UsdGeom.Mesh):\n",
    "        mesh_prim = UsdGeom.Mesh(prim)\n",
    "        print(f'{mesh_prim.GetPrim().GetPrimPath()}: vertices={len(mesh_prim.GetPointsAttr().Get())}, faces={int(len(mesh_prim.GetFaceVertexIndicesAttr().Get())/3)}')\n",
    "        \n",
    "low_prim = stage.GetPrimAtPath('/World/Low/Simplewall')\n",
    "high_prim = stage.GetPrimAtPath('/World/High/Simplewall')\n",
    "\n",
    "# Get the low and high resolution primitives from the stage and convert to the necessary format:\n",
    "low_mesh, low_mesh_xform = mesh.get_mesh(low_prim)\n",
    "high_mesh, high_mesh_xform = mesh.get_mesh(high_prim)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e5643b1-29a4-41e4-9624-6f77a0b6768f",
   "metadata": {},
   "source": [
    "Here we just find some texture filepaths we'll use later in the notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "12b0f26e-32bd-40f7-9649-38ede1901509",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import os\n",
    "import pathlib\n",
    "\n",
    "textures_folder = './assets/simplewall'\n",
    "resampled_resolution = 512\n",
    "\n",
    "# Find all the .png textures to resample\n",
    "filenames = [filename for filename in os.listdir(textures_folder) if 'png' in filename]\n",
    "\n",
    "# Create the output folder, if necessary\n",
    "resampled_textures_folder = './assets/simplewall/resampled'\n",
    "if not os.path.isdir(resampled_textures_folder):\n",
    "    os.mkdir(resampled_textures_folder)\n",
    "\n",
    "heightmap_filenames = [filename for filename in os.listdir(textures_folder) if 'height' in filename]\n",
    "heightmap_filename = str(pathlib.Path(textures_folder) / heightmap_filenames[0]) if len(heightmap_filenames) > 0 else \"\"\n",
    "print(f'Heightmap filename {heightmap_filename}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "86eab515-1e17-4805-a08b-0f282ebb3467",
   "metadata": {},
   "source": [
    "A context object is required for all toolkit operations.  This context allocates internal resources that can be reused across multiple invocations of the toolkit operations so it's handy to keep and reuse as needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f98acaf0-290e-4503-9a53-a5a6f6721b03",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import micromesh_python as pymm\n",
    "\n",
    "context = pymm.createContext(verbosity=pymm.Verbosity.Info)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec720919-e162-4dea-bdc0-f0487c821eb0",
   "metadata": {},
   "source": [
    "### Settings<a id=\"baker_settings\"></a>\n",
    "\n",
    "Now lets create the settings object which will house some tweakable parameters that effect the resulting displaced micromap data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7b595015-d40a-4649-a20e-0ef18e58238c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "settings = pymm.BakerSettings()\n",
    "\n",
    "# Control amount of subdivision levels from 0-5\n",
    "settings.level = 5\n",
    "\n",
    "# True to allow the baker to automatically fit the direction bounds to the localized surface\n",
    "# False to use global min/max bounds fitting\n",
    "settings.fitDirectionBounds = True\n",
    "\n",
    "# True to enable compression, false otherwise\n",
    "# Note: the graphics driver cannot render uncompressed micromesh data\n",
    "settings.enableCompression = True\n",
    "\n",
    "# Compression factor in range 0-100\n",
    "settings.minPSNR = 45.0\n",
    "\n",
    "# Subdivision method:\n",
    "#   Uniform to use constant subdivision level (above) for all base triangles\n",
    "#   Adaptive3D to select base triangle subdivision level using details in local geometry\n",
    "#   AdaptiveUV to select base triangle subdivision level using details in UV+heightmap\n",
    "settings.subdivMethod = pymm.SubdivMethod.Adaptive3D"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9dd9ce9c-58bc-425e-bf2d-635b6f313750",
   "metadata": {},
   "source": [
    "### Texture Resampling<a id=\"texture_resampling\"></a>\n",
    "\n",
    "If you have assets with textures, it is important to resample those textures so they can be rendered correctly in the displaced mesh.  We can build construct a list of textures to resample for the baker utility.  In addition we can find the heightmap."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "80f2c732-8b1a-47ef-82eb-2971c89a54dc",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "resampler_inputs = []\n",
    "for filename in filenames:\n",
    "    resampler_input = pymm.ResamplerInput()\n",
    "    resampler_input.input.filepath = str(pathlib.Path(textures_folder) / filename)\n",
    "    resampler_input.input.type = pymm.TextureType.Generic\n",
    "    resampler_input.output.filepath = str(pathlib.Path(resampled_textures_folder) / filename)\n",
    "    resampler_input.output.width = resampled_resolution\n",
    "    resampler_input.output.height = resampled_resolution\n",
    "    resampler_input.output.format = pymm.TextureFormat.RGBA8Unorm\n",
    "    resampler_inputs.append(resampler_input)\n",
    "    print(f'Resampling {resampler_input.input.filepath} to {resampler_input.output.filepath}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "37b841e4-a395-4553-990e-b70d9a4beeb8",
   "metadata": {},
   "source": [
    "### Baking<a id=\"baking\"></a>\n",
    "\n",
    "With input meshes loaded, settings initialized, and resampled textures listed, we can set up the baker input.  There are a few ways we can bake displaced micromap data:\n",
    "\n",
    "* Low-resolution mesh + heightmap\n",
    "* Low-resolution mesh + high-resolution mesh\n",
    "* Low-resolution mesh + heightmap + high-resolution mesh\n",
    "\n",
    "All three options require the low-resolution mesh but the baker will also work with a combination of heightmap and high-resolution mesh inputs.  If both heightmap and high-resolution mesh inputs are supplied, then the high-resolution mesh is displaced using the heighmap and that displaced mesh is used as the tracing surface."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "51256fa0-3abb-4c49-a881-a4a83a8693ba",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "baker_input = pymm.BakerInput()\n",
    "baker_input.settings = settings\n",
    "baker_input.baseMesh = low_mesh\n",
    "baker_input.baseMeshTransform = low_mesh_xform\n",
    "baker_input.referenceMesh = high_mesh\n",
    "baker_input.referenceMeshTransform = high_mesh_xform\n",
    "baker_input.heightmap.filepath = heightmap_filename\n",
    "baker_input.heightmap.scale = 0.133119\n",
    "baker_input.heightmap.bias = -0.074694\n",
    "if len(resampler_inputs) > 0:\n",
    "    baker_input.resamplerInput = resampler_inputs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ffc0e294-5fd1-4705-9f75-4f0709407e41",
   "metadata": {
    "tags": []
   },
   "source": [
    "Now we can call the baker:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "efcf12d2-afb5-4fa7-8745-491dd15db61e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "micromesh_data = pymm.bakeMicromesh(context, baker_input)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf4af130-b701-419d-9feb-0ed3f18ebcd1",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Saving to .bary File Format<a id=\"save_to_bary\"></a>\n",
    "\n",
    "Alternatively, we can save out to a micromesh-specific .bary format.  This format will store all of the necessary micromap data and is fully supported by the C/C++ Displacement Micromap SDK.  The Python Toolkit allows you to save to simply write the micromesh to .bary easily:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8608c76b-ff6b-455c-b4a7-3c26704b84e2",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "bary_file = './assets/low.bary'\n",
    "pymm.writeBary(context, bary_file, low_mesh, micromesh_data, forceOverwrite=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c118228b-d9dc-4a4d-8eba-dddee363934b",
   "metadata": {},
   "source": [
    "### Restoring from .bary File Format<a id=\"restore_from_bary\"></a>\n",
    "\n",
    "Conversely, we can load a .bary file similarly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a10c7080-fd49-4c3c-9433-d1e29451ba3e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "restored_micromesh_data = pymm.readBary(context, bary_file, low_mesh)\n",
    "\n",
    "import numpy as np\n",
    "print(np.array_equal(restored_micromesh_data.values, micromesh_data.values))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "51f0285b-030a-4331-b47e-5eced8150a37",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "displaced_mesh = pymm.displaceMicromesh(context, low_mesh, micromesh_data)\n",
    "print(f'Triangles in displaced mesh: {displaced_mesh.triangleVertices.shape[0]}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eb4f4f65-24f0-4b76-85dc-eb071717e3f6",
   "metadata": {},
   "source": [
    "Now we can convert that displaced mesh back to USD and save out the stage:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "06cbbaf1-11b5-470f-beb9-322a61ef73d5",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "temp_stage = Usd.Stage.CreateInMemory()\n",
    "mesh.create_mesh('/World/displaced/simplewall', displaced_mesh, temp_stage)\n",
    "temp_stage.Export('./assets/displaced.usd')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "327f897c-649b-4b6b-91c6-d0fb27db344b",
   "metadata": {},
   "source": [
    "### Saving to USD<a id=\"save_to_usd\"></a>\n",
    "\n",
    "The resulting displaced micromap data can also be stored back into USD as primvar attributes and utilized by a renderer supporting micro-meshes.  These primvars can be created on the prim manually through the ```UsdGeom.PrimvarsAPI```, or preferably using the ```DisplacementMicromapAPI``` applied USD schema.  Here is a utility function that will create the necessary primvars and convert to USD from the numpy arrays in the micromesh data object (<a href=\"./utils/mesh.py\">inspect the source</a>):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0fae6fc4-1c58-4b32-925c-67d31604563f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "mesh.store_micromesh_primvars(micromesh_data, low_prim)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "37d7d01b-813f-4709-868e-477b2f32ba4c",
   "metadata": {},
   "source": [
    "The nvMicromesh USD module contains a schema for storing displacement micromap attribute data as primvars on the USD primitive.  Lets confirm the schema has been applied, or alternatively if that plugin was not built, that the primvars were created, and briefly look at the attributes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5a05a30-a721-4a5a-972f-0296122e7f01",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "try:\n",
    "    from nvMicromesh import DisplacementMicromapAPI\n",
    "\n",
    "    if low_prim.HasAPI(DisplacementMicromapAPI):\n",
    "        micromap_api = DisplacementMicromapAPI(low_prim)\n",
    "        micromesh_attributes = [attribute for attribute in dir(micromap_api) if \"GetPrimvarsMicromesh\" in attribute]\n",
    "        for attribute in micromesh_attributes:\n",
    "            print(attribute)\n",
    "        print(micromap_api.GetPrimvarsMicromeshValuesAttr())\n",
    "        print(np.array(micromap_api.GetPrimvarsMicromeshValuesAttr().Get(), dtype=int))\n",
    "    else:\n",
    "        print(\"DisplacementMicromapAPI not applied, run above cell\")\n",
    "except:\n",
    "    from pxr import UsdGeom\n",
    "    primvars_api = UsdGeom.PrimvarsAPI(low_prim)\n",
    "    micromesh_attributes = [attribute for attribute in primvars_api.GetPrimvars() if \"micromesh\" in attribute.GetName()]\n",
    "    for attribute in micromesh_attributes:\n",
    "        print(attribute.GetName())\n",
    "    print(primvars_api.GetPrimvar('micromesh:values'))\n",
    "    print(np.array(primvars_api.GetPrimvar('micromesh:values').Get(), dtype=int))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be2dbefd-4504-4c14-9ea5-812e4d36c505",
   "metadata": {},
   "source": [
    "## Remeshing<a id=\"remeshing\"></a>\n",
    "\n",
    "If the only mesh available is a high-resolution mesh we can utilize a remeshing algorithm to produce a suitable low-resolution base mesh. Or if a low-resolution mesh exists but has many non-isotropic or long and thin triangles, we can rework that mesh to be more suitable for micro-meshes.  The Displacement Micromap Toolkit provides a GPU-accelerated remeshing algorithm that does just that.  It is controllable through a number of settings to help guide the algorithm using error thresholds, decimation amounts, and even a guide on upper bound for triangle count.\n",
    "\n",
    "Lets load a new, more detailed mesh and show how to remesh it using the Toolkit:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "670119c0-2242-4c5a-bae4-f4bf678abae1",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pxr import Usd, UsdGeom\n",
    "\n",
    "reefcrab_stage = Usd.Stage.Open('./assets/reefcrab/reefcrab.usd')\n",
    "        \n",
    "reefcrab_prim = reefcrab_stage.GetPrimAtPath('/World/High/Reefcrab')\n",
    "\n",
    "reefcrab_mesh, reefcrab_mesh_xform = mesh.get_mesh(reefcrab_prim)\n",
    "print(f'Triangles in low-resolution mesh: {reefcrab_mesh.triangleVertices.shape[0]}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "55a3d547-5013-41f7-a230-77e7d8c94ca6",
   "metadata": {},
   "outputs": [],
   "source": [
    "remesher_settings = pymm.RemesherSettings()\n",
    "remesher_settings.decimationRatio=0.2\n",
    "remesher_settings.errorThreshold=90\n",
    "remesher_settings.maxSubdivLevel=4\n",
    "\n",
    "remeshed_mesh = pymm.remesh(context, reefcrab_mesh, remesher_settings)\n",
    "\n",
    "print(f'Triangles in remeshed mesh: {remeshed_mesh.triangleVertices.shape[0]}')\n",
    "print(f'Actual decimation ratio: {remeshed_mesh.triangleVertices.shape[0] / reefcrab_mesh.triangleVertices.shape[0]:.2f}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "227565bb-c61c-45b7-9ddf-bbd5aadb0b02",
   "metadata": {},
   "source": [
    "### Pre-Tessellation<a id=\"pretessellation\"></a>\n",
    "\n",
    "It might be necessary to introduce <i>more</i> detail into an mesh in order to produce a desireable micro-mesh. For example, consider a triangle mesh containing two triangles defining a simple heightmapped surface.  There may be more detail in that heightmap that cannot be managed by even the highest level of displaced micro-mesh subdivision level.  We can accomplish this by running a pre-tessellation algorithm. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f0d698ef-34f1-4318-a03c-03e7a9037926",
   "metadata": {},
   "outputs": [],
   "source": [
    "pretessellator_settings = pymm.PreTessellatorSettings()\n",
    "pretessellator_settings.maxSubdivLevel = 5\n",
    "pretessellator_settings.edgeLengthBased = True\n",
    "\n",
    "pretessellated_mesh = pymm.preTessellate(context, low_mesh, pretessellator_settings)\n",
    "print(f'Triangles in low-resolution mesh: {low_mesh.triangleVertices.shape[0]}')\n",
    "print(f'Triangles in remeshed mesh: {pretessellated_mesh.triangleVertices.shape[0]}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3cd89085-9740-4911-858d-eddcf3ba7ac8",
   "metadata": {},
   "source": [
    "### Full Pipeline<a id=\"full_pipeline\"></a>\n",
    "\n",
    "Now lets throw it all together and bake out displacement micromap data for the simple wall asset.  Since the low-resolution mesh has only 2 triangles and the displacement heightmap has a resolution of 2048, in order to reconstruct the full displaced heightmap as a micro-mesh, we need to pre-tesselate the base mesh to support the higher level of detail required for producing a micro-mesh from the heightmap:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "800a67cb-086e-43cc-b83e-094221a007d9",
   "metadata": {},
   "outputs": [],
   "source": [
    "pretessellator_settings = pymm.PreTessellatorSettings()\n",
    "pretessellator_settings.maxSubdivLevel = 5\n",
    "pretessellator_settings.edgeLengthBased = True\n",
    "\n",
    "print(\"Pre-tessellating...\")\n",
    "pretessellated_mesh = pymm.preTessellate(context, low_mesh, pretessellator_settings)\n",
    "print(f'Triangles in low-resolution mesh: {low_mesh.triangleVertices.shape[0]}')\n",
    "print(f'Triangles in pre-tessellated mesh: {pretessellated_mesh.triangleVertices.shape[0]}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c27de3c3-2e79-47ae-a1aa-5f92ec882cd5",
   "metadata": {},
   "outputs": [],
   "source": [
    "settings = pymm.BakerSettings()\n",
    "settings.level = 5\n",
    "settings.fitDirectionBounds = True\n",
    "settings.enableCompression = True\n",
    "settings.minPSNR = 45.0\n",
    "settings.subdivMethod = pymm.SubdivMethod.Uniform\n",
    "\n",
    "baker_input = pymm.BakerInput()\n",
    "baker_input.settings = settings\n",
    "baker_input.baseMesh = pretessellated_mesh\n",
    "baker_input.baseMeshTransform = low_mesh_xform\n",
    "baker_input.referenceMesh = pretessellated_mesh\n",
    "baker_input.referenceMeshTransform = low_mesh_xform\n",
    "baker_input.heightmap.filepath = heightmap_filename\n",
    "baker_input.heightmap.scale = 0.133119\n",
    "baker_input.heightmap.bias = -0.074694\n",
    "\n",
    "print(\"Baking...\")\n",
    "micromesh_data = pymm.bakeMicromesh(context, baker_input)\n",
    "\n",
    "print(\"Displacing...\")\n",
    "displaced_mesh = pymm.displaceMicromesh(context, pretessellated_mesh, micromesh_data)\n",
    "\n",
    "print(f'Triangles in displaced mesh: {displaced_mesh.triangleVertices.shape[0]}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83ecb223-8d56-4558-92e2-2f44fc922a6e",
   "metadata": {},
   "source": [
    "Clean up the context when done:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "062b17a8-1c80-4e4f-82c7-54f5c44fd5ba",
   "metadata": {},
   "outputs": [],
   "source": [
    "context = None"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}