Forge API:

forge.commandline-nodejs

Note: For using this sample, you need a valid oAuth credential. Visit this page for instructions to get on-board.

Description

This sample exercises the Node.js engine as a command line utility to demonstrate the Forge OAuth application authorisation process and most of the Forge Services API such as Model Derivative, Bim360, Viewer, ...

Demonstrates the use of the Autodesk Forge API using a Node.js console application. Supports both 2 legged and 3 legged protocols.

Prerequisites

1. Forge Account: Learn how to create a Forge Account, activate subscription and create an app at this tutorial.
2. Visual Studio Code: other text editors could be used too, but Visual Studio Code is a widely used editor, see https://code.visualstudio.com/.
3. Node.js: basic knowledge of Node.js, see https://nodejs.org/en/.
4. JavaScript: basic knowledge.
5. If you want to use the BIM360 API - BIM 360 or other Autodesk storage account: if you want to use it with files from BIM 360 Docs then you must be an Account Admin to add the app integration. Learn about provisioning.

Setup/Usage Instructions

1. Install NodeJS

2. Download (fork, or clone) this project

3. Install Node.js dependency modules:
   

   npm install
   

4. Request your consumer key/secret key from https://forge.autodesk.com.

5. Set 2 environment variables FORGE_CLIENT_ID / FORGE_CLIENT_SECRET
   Mac OSX/Linux (Terminal)

   export FORGE_CLIENT_ID=<<YOUR FORGE CLIENT ID>>
   export FORGE_CLIENT_SECRET=<<YOUR FORGE CLIENT SECRET>>
   

   Windows (use Node.js command line from Start menu)

   set FORGE_CLIENT_ID=<<YOUR FORGE CLIENT ID>>
   set FORGE_CLIENT_SECRET=<<YOUR FORGE CLIENT SECRET>>
   

   If you only want to use Model Derivative, Data Management/OSS, Design Automation, Reality Capture - you can stop here

6. Set an environment variable PORT (This is for running either BIM360 API or the Viewer)
   Mac OSX/Linux (Terminal)

   export PORT=<<YOUR PORT NUMBER>>
   

   Windows (use Node.js command line from Start menu)

   set PORT=<<YOUR PORT NUMBER>>
   

7. Note for the 3 legged commands: while registering your keys, make sure that the callback you define for your callback (or redirect_uri) match your localhost and PORT number. Default is : http://localhost:3006/oauth Mac OSX/Linux (Terminal)

   export FORGE_CALLBACK=<<YOUR FORGE CALLBACK URL>>
   

   Windows (use Node.js command line from Start menu)

   set FORGE_CALLBACK=<<YOUR FORGE CALLBACK URL>>
   

8. Provision your application key on the BIM360 application integration page. Learn about provisioning.

Note: If you do not want to set environement variables, edit the forge.js file and replace the placeholders by the values listed above.

Usage

The utility provides help information for the commands and arguments. Use the --help option to access it.

Here are few examples (click ► to expand):

oAuth (2 legged) + DM/OSS + Model Derivative

# Do authorization.
node forge.js 2legged

# Create a bucket. Bucket name must be lower case and valid characters.
node forge.js buckets new my_bucket_name

# Upload a model.
node forge.js objects put Au.obj

# Register the model to get it translated.
node forge.js objects translate Au.obj

# Wait until the translation completes.
# Translation is complete when it reaches 'success - 100%'
node forge.js objects progress Au.obj

# Create an HTML page with your URN and a read-only access token to view the SVF.
node forge.js html get urn:adsk.objects:os.object:my_bucket_name/Au.obj ./bubbles/Au.obj.html

# Create an HTML page with your URN and a read-only access token to view the OTG version.
node forge.js html get urn:adsk.objects:os.object:my_bucket_name/Au.obj ./bubbles/Au.obj.html --otg

# Start local server and load the HTML page.
open http://localhost:$PORT/Au.obj.html & http-server ./bubbles/

oAuth (3 legged) + DM/BIM360

# Do authorization/authentication.
node forge.js 3legged auto

# Get the list of Hubs.
node forge.js hubs ls

# Get the list of projects.
node forge.js projects ls $hubid

# Get the entire project data tree.
node forge.js projects tree $hubid $projectid -f

# Refresh the access token
node forge.js 3legged refresh

# Create an HTML page with your URN and a read-only access token to view the SVF.
node forge.js html get $versionid ./bubbles/output.html

# Create an HTML page with your URN and a read-only access token to view the OTG version.
node forge.js html get $versionid ./bubbles/output.html --otg

# Start local server and load the HTML page.
open http://localhost:$PORT/Au.obj.html & http-server ./bubbles/

Note your access token, bucket name and other information are saved in the data folder to be used as default values by the utility, but you can edit them as you wish.

SVF and OTG bubble

Forge provides a service to extract CAD design file information into what Autodesk engineers calls a Bubble. The SVF Bubble is a collection of files (pack files for mesh, images for tecxtures, json for manifest and metadata) and is the default output "format" for the Model Derivative API, and consumed by the Viewer.

Recently, the Autodesk engineers refined the process to make a lightweight Bubble for AEC/BIM outputs, called OTG. While it was designed for AEC/BIM, OTG would still work for our scenarios but not guarantee on the reduction ratio compared to SVF. The Viewer also supports OTG natively, and would nicely switch to OTG with no code change other than the initializer configuration.

OTG de-duplication

OTG uses a de-duplication process of meshes. So think of a wall as a cube. And many walls are just a cube that is squished and rotated into place. So imagine all walls of a building represented by a single cube with many transforms. This saves storage space (data transfer). BUT.... It also significantly improves render performance, with GPU instancing. You send a single cube mesh to the GPU and thousands of tiny transforms as a single draw-call, thus drawing signicantly more triangles per frame.

Similar to the cube primative for walls, the same thing happens for Re-Bar and hand-rails, it's mostly de-duplication of a 'cylindrical primitive'.

OTG precision

OTG (centered at the origin) can theoretically measure a 20km stretch at 4.6 micron precision, which is just equivalent to the limit of 32 bit float precision. Currently, OTG uses a single double precision offset for each model.

Linear designs or geospatial models are yet to be validated with OTG. We are looking for feedback.

---

Further reading

Documentation:

• BIM 360 API and App Provisioning
• Data Management API
• Viewer

Tutorials:

• View BIM 360 Models
• Retrieve Issues

Blogs:

• Forge Blog
• Field of View, a BIM focused blog

OTG:

• Load OTG with ForgeViewer sample

License

This sample is licensed under the terms of the MIT License. Please see the LICENSE file for full details.

Written by

Cyrille Fauvel
Forge Partner Development
http://developer.autodesk.com/
http://around-the-corner.typepad.com