{"id":19553138,"url":"https://github.com/needle-tools/usd-viewer","last_synced_at":"2025-10-07T01:52:59.532Z","repository":{"id":188581907,"uuid":"679013620","full_name":"needle-tools/usd-viewer","owner":"needle-tools","description":"USD Web Viewer based on Autodesk's WASM USD bindings and a three.js Hydra render delegate","archived":false,"fork":false,"pushed_at":"2025-09-10T14:22:04.000Z","size":92467,"stargazers_count":123,"open_issues_count":15,"forks_count":15,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-10-01T08:51:11.930Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cloud.needle.tools","language":"JavaScript","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/needle-tools.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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-15T23:06:26.000Z","updated_at":"2025-09-30T10:20:09.000Z","dependencies_parsed_at":"2024-05-31T09:31:51.313Z","dependency_job_id":"5ab08944-0ada-4fd5-b433-7d4e70dcd765","html_url":"https://github.com/needle-tools/usd-viewer","commit_stats":null,"previous_names":["needle-tools/usd-viewer"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/needle-tools/usd-viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-tools%2Fusd-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-tools%2Fusd-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-tools%2Fusd-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-tools%2Fusd-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/needle-tools","download_url":"https://codeload.github.com/needle-tools/usd-viewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-tools%2Fusd-viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278708030,"owners_count":26031932,"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","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-11T04:21:47.001Z","updated_at":"2025-10-07T01:52:59.527Z","avatar_url":"https://github.com/needle-tools.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# USD Viewer\n\nA USD viewer on the web.  \n[Open USD Viewer](https://usd-viewer.needle.tools/)  \n\nThere are two main parts:  \n- [USD WASM bindings by Autodesk](https://autodesk-forks.github.io/USD/usd_for_web_demos/)\n- A [Three.js](https://threejs.org/) Hydra Delegate for rendering, originally by Autodesk and improved by hybridherbst\n\n## Info and Known Issues\n\n- You can load USDZ files, folders, multiple files.  \n  - Try the Kitchen Set from [here](https://openusd.org/release/dl_kitchen_set.html)\n  - Try assets from [Asset Explorer](https://asset-explorer.needle.tools)\n- There is a heuristic to determine what the root file is - it's not perfect.  \n- Up axis is only supported for the root file (and very hacky).  \n- Variants are loaded but can't be switched.  \n- The viewer uses SharedArrayBuffers, which have strict header and origin requirements and are not supported on all platforms. \n\n### Limitations\n\n- Skinned meshes aren't supported. \n- Vertex colors aren't supported. \n- Point instancing isn't supported.  \n- MaterialX isn't supported.  \n- LightsAPI isn't supported.  \n- Texture paths currently can't be resolved correctly for nested USDZ files. One level is fine.\n    - Fixing this would require adjustments to the WASM bindings.\n\n## Contribute\n\n- [Report an issue](https://github.com/needle-tools/usd-viewer/issues)  \n- [Reach out](hi@needle.tools)\n\n## Development\n\n- clone this repository\n- run `npm install`\n- run `npm run start`\n- open `http://localhost:\u003cport\u003e` in your browser (Note: 0.0.0.0 won't work since it doesn't have SharedArrayBuffer permissions)\n\nThe three.js Hydra Delegate is in `public/ThreeJsRenderDelegate.js`.  \nLoading and rendering are currently intermingled in `public/index.html`.  \n\n### Rebuilding USD-wasm\n\nNOTE: Origins for these instructions can be found [here](https://github.com/autodesk-forks/USD/blob/adsk/feature/webgpu/pxr/usdImaging/bin/usdviewweb/README.md)\n\n#### Getting Setup\n\n1. Setup emscripten if it's not already setup.\n    1. Download and Install [emscripten](https://emscripten.org) from [HERE](https://emscripten.org/docs/getting_started/downloads.html).\n    2. MacOS\n        1. Download and install the latest SDK tools.\n            1. `./emsdk install 3.1.55`\n        2. Make the specific SDK \"active\" for the current user. (writes .emscripten file)\n            1. `./emsdk activate 3.1.55`\n        3. Activate PATH and other environment variables in the current terminal\n            1. `source ./emsdk_env.sh`\n      3. Windows\n          1. Download and install the latest SDK tools.\n              1. `emsdk install 3.1.55`\n          2. Make the specific SDK for the current user. (writes .emscripten file)\n              1. `emsdk activate 3.1.55`\n  2. Setup CMAKE\n      1. Install\n      2. Open CMAKE, open \"Tools/How to install for Command Line Use\"\n      3. Copy the command there and run in the same terminal, e.g.\n         `PATH=\"/Applications/CMake.app/Contents/bin\":\"$PATH\"`\n  2. Pull [this branch](https://github.com/autodesk-forks/USD/tree/adsk/feature/webgpu) from Autodesk's USD fork\n      1. `git clone --recursive https://git.autodesk.com/autodesk-forks/usd/tree/adsk/feature/webgpu`\n\n#### Building\n\n##### Release\n\n1. Go into the root of usd source repo, if the folder name is \"usd_repo\"\n    1. `cd usd_repo`\n2. Build USD with the --emscripten flag, for example \"../build_dir\" is your local build folder\n    2. `python3 ./build_scripts/build_usd.py --build-target wasm ../build_dir`\n3. This will put the resulting files in ../build_dir/bin\n    1. `emHdBindings.js`\n    2. `emHdBindings.wasm`\n    3. `emHdBindings.worker.js`\n    4. `emHdBindings.data`\n    4. Note: It's possible the build will fail due to comments in `pxr/base/arch/hints.h`, removing all comments from line 1-26 allowed the build to complete successfully\n4. Run `wasm-opt -Oz -o \"../build_dir/bin/emHdBindings.wasm\" \"../build_dir/bin/emHdBindings.wasm\" --enable-bulk-memory --enable-threads` to shrink the wasm file more.\n5. Patch emHdBindings.js to enable the following support, unable to currently do these things as part of the normal build process\n    1. Support for arguments\n        - `patch emHdBindings.js \u003c patches/arguments_1.patch` \n        - `patch emHdBindings.js \u003c patches/arguments_2.patch` \n            - THIS PATCH DOES NOT WORK\n            - Copy the following lines:\n            ```\n            return function (\n                moduleArg = {\n                // module overrides can be supplied here\n                locateFile: (path, prefix) =\u003e {\n                    if (!prefix)\n                    prefix = _scriptDir.substr(0, _scriptDir.lastIndexOf(\"/\") + 1);\n                    return prefix + path;\n                },\n                ...args,\n                },\n            ) {\n            ```\n            And replace this line:\n            -  `return function (moduleArg = {}) {`\n    2. Disable ABORT so that one bad file doesn't corrupt the entire session\n        - `patch emHdBindings.js \u003c patches/abort.patch` \n    3. Add file system functions to the module\n        - `patch emHdBindings.js \u003c patches/fileSystem.patch` \n            - THIS PATCH DOES NOT WORK\n            - Add these lines \n            ```\n            Module[\"FS_readdir\"] = FS.readdir;\n            Module[\"FS_analyzePath\"] = FS.analyzePath;\n            ```\n            right after \n            - `Module[\"PThread\"] = PThread;`\n\n##### Debug\n1. Install [ C/C++ DevTools Support (DWARF)](https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb)\n2. Update https://github.com/needle-tools/OpenUSD/blob/needle/feature/wasm-improvements/pxr/usdImaging/hdEmscripten/CMakeLists.txt#L89, instead of `-Oz` use `-O3 -g`\n3. Go into the root of usd source repo, if the folder name is \"usd_repo\"\n    1. `cd usd_repo`\n4. Build USD with the --emscripten flag, for example \"../build_dir\" is your local build folder\n    2. `python3 ./build_scripts/build_usd.py --build-target wasm --build-variant debug ../build_dir`\n5. This will put the resulting files in ../build_dir/bin\n    1. `emHdBindings.js`\n    2. `emHdBindings.wasm`\n    3. `emHdBindings.worker.js`\n    4. `emHdBindings.data`\n    5. Note: It's possible the build will fail due to comments in `pxr/base/arch/hints.h`, removing all comments from line 1-26 allowed the build to complete successfully\n6. Patch emHdBindings.js to enable the following support, unable to currently do these things as part of the normal build process\n    1. Support for arguments\n        - `patch emHdBindings.js \u003c arguments_1.patch` \n        - `patch emHdBindings.js \u003c arguments_2.patch` \n            - THIS PATCH DOES NOT WORK\n            - Copy the following lines:\n            ```\n            return function (\n                moduleArg = {\n                // module overrides can be supplied here\n                locateFile: (path, prefix) =\u003e {\n                    if (!prefix)\n                    prefix = _scriptDir.substr(0, _scriptDir.lastIndexOf(\"/\") + 1);\n                    return prefix + path;\n                },\n                ...args,\n                },\n            ) {\n            ```\n            And replace this line:\n            -  `return function (moduleArg = {}) {`\n    2. Disable ABORT so that one bad file doesn't corrupt the entire session\n        - `patch emHdBindings.js \u003c abort.patch` \n    3. Add file system functions to the module\n        - `patch emHdBindings.js \u003c fileSystem.patch` \n            - THIS PATCH DOES NOT WORK\n            - Add these lines \n            ```\n            Module[\"FS_readdir\"] = FS.readdir;\n            Module[\"FS_analyzePath\"] = FS.analyzePath;\n            ```\n            right after \n            - `Module[\"PThread\"] = PThread;`\n7. Run `npm start`\n8. Go to http://localhost:3003 (or wherever the app is running)\n9. Open up Chrome Dev Tools\n10. Go to Sources -\u003e (vertical ellipsis) -\u003e Group by Authored/Deployed\n11. Under Authored, you can go through to the pxr files to set breakpoints in the c++ code.\n\n##### Build Script\nThere is a build script [here](https://github.com/needle-tools/OpenUSD/blob/needle/feature/wasm-improvements/buildAndMove.sh) which tries to make building easier. Set the mode, build directory and destination directory to deal with the file movement.\n\nUsage: `./buildAndMove.sh --mode release --build-dir ../build-wasm --destination-dir /Users/andrewbeers/git/needle/usd-viewer/public`\n\nNOTE: this does not support patching yet as patching doesn't completely work yet\nNOTE: this does not update CMakeLists.txt for debug mode automatically\n\n\n## Origin\n\nBased on [autodesk-forks.github.io/USD/usd_for_web_demos](https://autodesk-forks.github.io/USD/usd_for_web_demos/)  \nCode here: [github.com/autodesk-forks/USD/tree/gh-pages](https://github.com/autodesk-forks/USD/tree/gh-pages)\nThis project: [github.com/needle-tools/usd-viewer](https://github.com/needle-tools/usd-viewer)\n\n## Improvements over the original viewer\n\n- added drag-and-drop loading\n- dropping folders and multiple files is supported (experimental)\n- g,b texture channels were missing with RBGFormat\n- files of the form somefile.usdz[./textures/myTexture.jpg] weren't resolved correctly\n- UVMap primvar type wasn't correctly resolved to uv\n- support for texture wrap modes\n- support for texture transforms (rotation isn't properly working yet)\n- fixed output color space, added neutral HDR, fixed point light changing color appearance of scene\n- very hacky support for up axis on the root file\n- added camera orbit dampening\n- setting policy headers server-side instead of via ServiceWorker\n\n## Headers\n\nSome JavaScript features used here require specific HTTP headers (SharedArrayBuffers).  \nThis was originally achieved by using the service worker from here: [github.com/gzuidhof/coi-serviceworker](https://github.com/gzuidhof/coi-serviceworker/blob/master/coi-serviceworker.js).  \n\nNow, headers are set server-side which should have wider support / better caching.\n\n```\nres.setHeader(\"Cross-Origin-Embedder-Policy\", \"require-corp\");\nres.setHeader(\"Cross-Origin-Opener-Policy\", \"same-origin\");\n```\n\n## Credits\n\nBy [Needle](https://needle.tools) \u0026 [prefrontal cortex](https://prefrontalcortex.de)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedle-tools%2Fusd-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneedle-tools%2Fusd-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedle-tools%2Fusd-viewer/lists"}