The (S)STK provides:
- Web-based framework for viewing models and scenes.
- Various web-based annotation interfaces for annotating models and scenes
- Batch processing component for doing analysis on scenes and offscreen rendering (see ssc/README.md)
- Server-side rendering
-
The SSTK can be used on Linux, MacOS and Windows systems.
Prerequisites for Ubuntu:
sudo apt-get install build-essential libxi-dev libglu1-mesa-dev libglew-dev libvipsPrerequisites for MacOS: Please install Xcode
For some older version of node (v10.x.x) and on some platforms,
node-gypmay require python 2.7 so if you get an error with node-gyp, make sure the python in your path is python 2.7. -
Install node.js v14.16.0. Using the Node Version Manager (nvm) is the easiest way to install node.js on most systems.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash source ~/.bashrc nvm install v14.16.0If you use
zshinstead ofbash, replacesource ~/.bashrcwithsource ~/.zshrc. Confirm above works usingnode -vat the terminal. -
Build the STK library. Enter the root directory of the repo (
${STK})cd ${STK} ./build.shThis will build the STK library that is needed by the server and command line scripts.
Note 1: We are using an older version of node with pinned packages that may have vulnerabilities. So you may get a warning indicating that there are vulnerabilities.
DO NOT run
npm audit fix- that will upgrade some of the packages and cause the code to break.Note 2: if node-gyp gl build issue is encountered due to missing
anglesubmodule, this is due to a bug (npm/cli#2774). To resolve this, downgrade to an oldernpmthroughnpm install -g npm@'^6.4.11'prior to running build. -
Running the server (see server/README.md for details
cd server ./run.shVisit http://localhost:8010 in your browser (Chrome is recommended)!
-
Running command line scripts
See ssc/README.md.
To use the STK, you will need to get yourself some assets. There are several open-source datasets that you can use with the STK. Many of these datasets require agreeing to a license and terms of use,
- 3D Models
- ShapeNet is a large dataset of 3D models.
- Synthetic Scenes
- Stanford Scene Database consist of 150 synthetic scenes.
- SUNCG is a large indoor dataset with over 45K houses.
- Reconstructions
The STK has been developed to be able to easily view and annotate 3D assets. Specifically, parts of ShapeNet, SUNCG, ScanNet, and Matterport3D were all developed using the STK.
model-viewer: Model viewing interfacemodel-categorizer.html: Model categorization interfacescene-viewer.html: Scene Viewer
If you are developing and changing the STK, the following will monitor changes to the client / server code.
- In the
/clientfolder, run this command:
NODE_ENV=dev npm run build
- In the
/serverfolder, run this command:
npm run watch
You can also specify the remote instance to use for various webservices (such as solr search) by specifying
STK_REMOTE_HOST=https://<remote-server-name>/scene-toolkit npm run watch
To build different builds of the client STK library
cd client- Type
npm installto install client dependencies - Run
npm run buildto package the stk source files- Use
NODE_ENV=dev npm run buildto build source maps and have webpack watch for changes. - Use
NODE_ENV=prod npm run buildto optimize (including minify) the JS assets.
- Use
For convenience a build.sh script is provided that will run the two steps above.
You will need to repeat the build step every time the client source files are changed or use NODE_ENV=dev npm run build to watch and rebuild as you develop!
cd clientfrom the repository root- run
npm run jsdoc - Open the generated
jsdoc/index.htmlpage with a browser
Once you have built the client library, to start the server do the following from the root repository directory:
cd server
npm install
npm start # or use "npm watch" to run the server using nodemon and automatically restart the server on changes
The server/run.sh script is provided that will run the above steps together.
See server/README.md for details, including how to deploy a new instance.
For routine local development, here are the usual steps:
- Start webpack build process in watch mode by calling
NODE_ENV=dev npm run buildinside theclient/directory. If new dependencies have been introduced, you may get an unresolved module error and will need to runnpm installfirst. With watch mode, you won't have to manually runnpm run buildwhen you change the client code (it will monitor changes in the client directory and rebuilt automatically). - In a separate terminal, start the server process by calling
npm run watchinside theserver/directory. Again, if new server code dependencies have been introduced, you may need annpm installcall to resolve them first. Running the server in watch mode will monitor changes in the server directory and restart the server automatically. - Go to a browser window and pull up
localhost:8010/index.htmlor any other entry point (such asscene-viewer.html). - If you just need a one-time build of the toolkit, copy out the
client/build/STK.bundle.js(afternpm run build) to the target directory.
Versioning conventions:
- The
masterbranch contains latest mainstream (with potential bug fixes over latest release) - The
devbranch contains large (potentially breaking) changes - The
v0.5.xbranch (and similar future versioned branches) contain the latest release of that form Versioning workflow: develop onmasterfor small bug fixes or ondevfor large changes. When ready to release branch, make sure to update appropriatev0.5.xor similar latest release branch, and also tag with exact version number (e.g.,v0.5.3).
The annotation tools use a MySQL database for storing annotations and an Apache solr index for indexing assets.
SQL DDL scripts for creating data tables are in scripts/db. See MySQL installation instructions for installing your own instance of MySQL and run the provided DDL scripts in scripts/db to create the annotation tables.
See wiki for how to prepare your assets for annotation. Once you have setup a MySQL server, you should edit config.annDb in server/config/index.js to point to your MySQL instance.
The server uses reverse proxying to access various other resources and web services.
Edit server/app/routes/proxy-rules.js to add your own proxy rules for accessing your own resources.
If you run your own solr instance locally, you should set the environment variable USE_LOCAL=1. This can be done by manually or by copying the env.example.sh to env.sh and modifying it as necessary. It will be used in the provided build.sh and run.sh.
For storing annotations, you will need to setup your own MySQL server. Once you have setup a MySQL server, you should edit config.annDb in server/config/index.js to point to your MySQL instance.
If your MySQL server is limited to access by localhost only, you can use ssh tunneling to forward 3306 from a remote machine to localhost through SSH connection:
ssh -L 3306:localhost:3306 -L <host> -N
cd clientfrom the repository root- run
npm run jsdoc - Open the generated
jsdoc/index.htmlpage with a browser
Refer to CHANGELOG.md for a record of notable changes.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent