Version update 1.0.0 (#1)

* Version update 1.0.0 * Update the example in README.md * Add a package script, publish:dist * chore: remove KHR_interactivity extension * chore: remove unused functions from Util, update API documents * chore: update package.json
amzn · Dec 17, 2024 · 95fa641 · 95fa641
1 parent fe49b0a
commit 95fa641
Show file tree

Hide file tree

Showing 77 changed files with 19,290 additions and 21 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -0,0 +1,37 @@
+{
+    "ignorePatterns": ["/*", "!/src", "!/test"],
+    "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "plugin:prettier/recommended"],
+    "parser": "@typescript-eslint/parser",
+    "plugins": ["import", "@typescript-eslint", "import-path"],
+    "rules": {
+        "@typescript-eslint/ban-ts-comment": "warn",
+        "@typescript-eslint/member-ordering": "error",
+        "@typescript-eslint/no-explicit-any": "warn",
+        "@typescript-eslint/no-unused-vars": "warn",
+        "arrow-body-style": "off",
+        "prefer-arrow-callback": "off",
+        "no-multiple-empty-lines": ["error", { "max": 1, "maxEOF": 0 }],
+        "import/order": [
+            "error",
+            {
+                "newlines-between": "always",
+                "alphabetize": { "order": "asc", "caseInsensitive": true }
+            }
+        ],
+        "import-path/forbidden": ["error", [
+            {
+                "match": "^@babylonjs/(core|gui|loaders|materials)$",
+                "message": "Use full path to benefit from tree-shaking, https://doc.babylonjs.com/setup/frameworkPackages/es6Support#tree-shaking. For example, 'import { Engine } from \"@babylonjs/core/Engines/engine\";'"
+            }
+        ]],
+        "prettier/prettier": [
+            "error",
+            {
+                "printWidth": 120,
+                "tabWidth": 4,
+                "singleQuote": true,
+                "trailingComma": "all"
+            }
+        ]
+    }
+}
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,10 @@
+.vscode
+*.swp
+.DS_Store
+lib
+node_modules
+dist
+.idea
+coverage
+*.tgz
+docs
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+- BabylonJS version: [`7.34.2`](https://github.com/BabylonJS/Babylon.js/releases/tag/7.34.2)
+- Initialized the repository
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,7 +11,7 @@ information to effectively respond to your bug report or contribution.
 
 We welcome you to use the GitHub issue tracker to report bugs or suggest features.
 
-When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
+When filing an issue, please check [existing open](https://github.com/amzn/lib-3d-scene-viewer/issues), or [recently closed](https://github.com/amzn/lib-3d-scene-viewer/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20), issues to make sure somebody else hasn't already
 reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
 
 * A reproducible test case or series of steps
@@ -21,6 +21,7 @@ reported the issue. Please try to include as much information as you can. Detail
 
 
 ## Contributing via Pull Requests
+
 Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
 
 1. You are working against the latest source on the *main* branch.
@@ -31,29 +32,59 @@ To send us a pull request, please:
 
 1. Fork the repository.
 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
-3. Ensure local tests pass.
-4. Commit to your fork using clear commit messages.
-5. Send us a pull request, answering any default questions in the pull request interface.
-6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+3. Add API documentation to all added public functions and classes using TSDoc syntax.
+4. Run `npm run build` locally and make sure it's successfully executed.
+5. Run `npm run test` for unit tests. Ensure local tests pass.
+6. Commit to your fork using clear commit messages.
+7. Send us a pull request, answering any default questions in the pull request interface.
+8. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
 
 GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
 
-## Finding contributions to work on
-Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
+## Backward Compatibility
+
+Any code change that breaks backward compatibility should be avoided. 
+You can always add to an API, but cannot remove anything from one.
+
+
+## Development
+
+See [README.md](README.md#development).
+
+
+## Code Style
+
+We use ESLint on the code to ensure a consistent style. 
+Any new code committed must pass our ESLint tests by running:
+
+```
+npm run lint
+```
+
+
+## Documentation
+
+All public APIs must have API documentation. 
+We use `typedoc` to generate documentation files:
+
+```
+npm run docs
+```
+
+The files are generated under `./dist/docs/` folder.
 
 
 ## Code of Conduct
+
 This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
 For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
 [email protected] with any additional questions or comments.
 
 
-## Security issue notifications
-If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
-
-
 ## Licensing
 
-See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
+See the [LICENSE](https://github.com/amzn/lib-3d-scene-viewer/blob/master/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
+
+We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes.
diff --git a/NOTICE b/NOTICE
@@ -1 +1,2 @@
+lib-3d-scene-viewer
 Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
diff --git a/README.md b/README.md
@@ -1,17 +1,210 @@
-## My Project
+# lib-3d-scene-viewer
 
-TODO: Fill this README out!
+![npm version](https://img.shields.io/badge/npm_package-1.0.0-green)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Be sure to:
+**lib-3d-scene-viewer** is a package based on [Babylon.js](https://www.babylonjs.com/).
+It provides preset configurations for quickly setting up a 3D scene viewer.
 
-* Change the title in this README
-* Edit your repository description on GitHub
 
-## Security
+## Getting Started
 
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+### Installation
 
-## License
+The package can be installed from [npm](https://npmjs.org/):
+
+```shell
+npm install @amazon/lib-3d-scene-viewer
+```
+
+
+### Usage
+
+[Take a look at an example](src/dev/v3dViewer.ts)
+
+```ts
+// Needed for BabylonJS debug layer
+import '@babylonjs/inspector';
+import { Config } from '@amazon/lib-3d-scene-viewer/config/config';
+import { Model } from '@amazon/lib-3d-scene-viewer/model/model';
+import { Scene } from '@babylonjs/core/scene';
+import { V3D_CONFIG } from '@amazon/lib-3d-scene-viewer/config/preset/v3dConfig';
+import { V3DScene } from '@amazon/lib-3d-scene-viewer/scene/v3dScene';
+
+(async function () {
+    /////////////////////////////////////////
+    // Step 0: create a canvas DOM element //
+    /////////////////////////////////////////
+
+    const canvas = document.createElement('canvas');
+    document.body.appendChild(canvas);
+
+    ////////////////////////////////////////////
+    // Step 1: create an instance of V3DScene //
+    ////////////////////////////////////////////
+
+    // V3D_CONFIG is a preset config
+    const v3dScene = new V3DScene(canvas, V3D_CONFIG, {
+        // Override file paths if needed
+        lightingConfig: {
+            StudioSide3Top1: {
+                type: 'env',
+                filePath: 'public/ibl/Studio_Side3Top1_256.env',
+            },
+        },
+        basisTranscoder: {
+            urlConfig: {
+                jsModuleUrl: 'public/js/basis/basis_transcoder.js',
+                wasmModuleUrl: 'public/js/basis/basis_transcoder.wasm',
+            },
+        },
+        ktx2Decoder: {
+            urlConfig: {
+                jsDecoderModule: 'public/js/ktx2/babylon.ktx2Decoder.js',
+                jsMSCTranscoder: 'public/js/ktx2/msc_basis_transcoder.js',
+                wasmMSCTranscoder: 'public/js/ktx2/msc_basis_transcoder.wasm',
+                wasmUASTCToASTC: 'public/js/ktx2/uastc_astc.wasm',
+                wasmUASTCToBC7: 'public/js/ktx2/uastc_bc7.wasm',
+                wasmUASTCToR8_UNORM: null,
+                wasmUASTCToRG8_UNORM: null,
+                wasmUASTCToRGBA_SRGB: 'public/js/ktx2/uastc_rgba8_srgb_v2.wasm',
+                wasmUASTCToRGBA_UNORM: 'public/js/ktx2/uastc_rgba8_unorm_v2.wasm',
+                wasmZSTDDecoder: 'public/js/ktx2/zstddec.wasm',
+            },
+        },
+        dracoCompression: {
+            decoders: {
+                wasmBinaryUrl: 'public/js/draco/draco_decoder_gltf.wasm',
+                wasmUrl: 'public/js/draco/draco_decoder_gltf_nodejs.js',
+                fallbackUrl: 'public/js/draco/draco_decoder_gltf.js',
+            },
+        },
+        meshoptCompression: {
+            decoder: {
+                url: 'public/js/meshopt/meshopt_decoder.js',
+            },
+        },
+        enableDragAndDrop: true,
+    });
+
+    /////////////////////////////////////////////////////////////////////
+    // Step 2: register any observers using V3DScene.observableManager //
+    /////////////////////////////////////////////////////////////////////
+
+    v3dScene.observableManager.onConfigChangedObservable.add((config: Config) => {
+        console.log('Updated config:', config);
+    });
+
+    v3dScene.observableManager.onModelLoadedObservable.add((model) => {
+        model.showShadowOnGroundDepthMap();
+        model.moveCenterToTargetCoordinate();
+
+        const radius = 2 * Math.max(...model.getOverallBoundingBoxDimensions().asArray());
+        v3dScene.updateConfig({
+            cameraConfig: {
+                ArcRotateCamera: {
+                    type: 'arcRotateCamera',
+                    radius: radius,
+                    lowerRadiusLimit: radius * 0.05,
+                    upperRadiusLimit: radius * 5,
+                    minZ: radius * 0.02,
+                    maxZ: radius * 40,
+                },
+            },
+        });
+    });
+
+    //////////////////////////////////
+    // Step 3: call init() function //
+    //////////////////////////////////
+
+    await v3dScene.init();
+
+    /////////////////////////////////
+    // Step 4: load glTF/glb model //
+    /////////////////////////////////
+
+    const model: Model = await v3dScene.loadGltf('public/model/mannequin.glb', true);
+    console.log('Bounding box dimensions:', model.getOverallBoundingBoxDimensions());
+
+    //////////////////////////////////////////////////////////////////////////////////////////////////
+    // Step 5 (Optional): call updateConfig() to update scene setup and/or handle user interactions //
+    //////////////////////////////////////////////////////////////////////////////////////////////////
+
+    await v3dScene.updateConfig({
+        sceneConfig: {
+            useLoadingUI: true,
+        },
+    });
+
+    // Access BabylonJS scene object
+    const babylonScene: Scene = v3dScene.scene;
+    console.log('Active Cameras:', babylonScene.activeCameras);
+
+    // Toggle BabylonJS debug layer
+    document.addEventListener('keydown', async (event) => {
+        const key = event.key;
+        // Pressing '?' should show/hide the debug layer
+        if (key === '?') {
+            v3dScene.toggleDebugMode();
+        }
+    });
+})();
+```
+
+
+### Resource
+
+This package provides a few resources including IBL files, decoder/transcoder files, and 3D models.
+These resources can be found in [public](public) folder or `@amazon/lib-3d-scene-viewer/public` via npm.
 
-This project is licensed under the Apache-2.0 License.
 
+### Config
+
+This packages uses [Config](src/config/config.ts) to set up engine, scene, camera, lighting, decoder files, etc.
+
+The full config parameters and default values can be found in [Config](src/config/config.ts).
+
+It also provides preset config files in [preset](src/config/preset) folder 
+or `@amazon/lib-3d-scene-viewer/config/preset`.
+
+
+## Development
+
+When developing the project, first install 
+[git](https://git-scm.com), 
+[Node.js](https://nodejs.org) 
+and [npm](https://www.npmjs.com/).
+
+Then, follow the steps to set up the development environment:
+
+```shell
+git clone [email protected]:amzn/lib-3d-scene-viewer.git
+cd lib-3d-scene-viewer
+npm install
+```
+
+The following scripts are available:
+
+| Command                  | Description                                                                                 |
+|--------------------------|---------------------------------------------------------------------------------------------|
+| `npm install`            | Install dependencies                                                                        |
+| `npm run build`          | Run the build step for all sub-projects                                                     |
+| `npm run clean`          | Remove all built artifacts                                                                  |
+| `npm run docs`           | Create API documentation                                                                    |
+| `npm run lint`           | Run ESLint                                                                                  |
+| `npm run pack:dist`      | Build the project and create an npm tarball under `dist` folder                             |
+| `npm run publish:dist`   | Publish the npm tarball                                                                     |
+| `npm run server`         | Run a web server and open a new browser tab pointed to [src/dev/index.ts](src/dev/index.ts) |
+| `npm run test`           | Run tests                                                                                   |
+| `npm run update-bjs-ver` | Update BabylonJS dependencies to a specific version                                         |
+
+
+## Contributing
+
+For more information take a look at [CONTRIBUTING.md](CONTRIBUTING.md).
+
+
+## License
+
+This library is licensed under the [Apache 2.0](LICENSE) License.
Original file line number	Diff line number	Diff line change
		@@ -1 +1,2 @@
		lib-3d-scene-viewer
		Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.