Cloud and Mobile

Boost your Web Application with C++! Emscripten, ASM.js, Web Assembly ...

By Philippe Leefsma (@F3lipek)

    I meant to take a look at the topic since a while but finally got time during a rainy weekend: asm.js, "an extraordinarily optimizable, low-level subset of JavaScript" and Web Assembly, "an experimental efficient low-level programming language for in-browser client-side scripting" ! 

    You can easily find lots of articles on that topic over the web, so I'm not planning to explain in details the theory... Rather than summing up again the same information from different sources, this blogpost is a deep dive from my own experience into digging how to compile a non-trivial piece of C++ into asm.js and Web Assembly (wasm). Then running them inside the browser from a custom test in order to benchmark the performances. Results are satisfying, to say the least.

    If you are ready for a sneak peek at the future of web development, keep reading!

I - Setting up the Emscripten tool chain

    The first step in the process is to setup the required tools that enable you to compile a piece of C++ into something that can be loaded into a browser. That project is called Emscripten, so the first thing you would do when opening the link, is to go to the Getting Started section and follow the instructions right? 

    Yes, but there is a trick... the standard install instructions are suitable to compile C++ into asm.js, but if you plan to compile into Web Assembly - I know you do - there is just a little difference: instead of installing the latest SDK, you need to install the incoming branch, which has BINARYEN compile option available out of the box.

    1/ Go to Emscripten SDK download page and make sure you have the prerequisite tools on your machine. The SDK runs on OSX, Windows and Linux

    2/ You will then build the SDK from source as per those instructions. You just need to instal the sdk-incoming-64bit as described in the tutorial, you do NOT need to install the master branch (no wasm support there yet - at the time of this writing)

    3/ Perform a check to see if emcc (the Emscripten compiler) is installed properly, I have it in my system path, so I can simply type emcc -v in a terminal:

    If you see something like this, then you are ready for the next thrill!

II - Back to the 90's, let's write some C++ 

    It's been a while since I hadn't written more than few lines of C++. Emscripten documentation is pretty good and the SDK comes which a bunch of samples, ranging from very basic to pretty advanced, so you probably want to go at least through the basic hello world tutorial.

    It's quite detailed, so I assume this goes smoothly on your side as well and you are now able to compile a single C++ file into asm.js, then load it into the demo web page that is produced when using the -o output.html:

./emcc tests/hello_world.c -o hello.html

 

    Almost the same emotion than the first C++ program I wrote on my PC!

    My goal here however is to write a slightly more advanced piece of code in order to compare its execution speed with plain JavaScript or we could say "human written JavaScript". A good candidate for that task that came naturally to my mind is the particle system I wrote few months ago, I already have the JavaScript ES6 version, so I just needed to write an equivalent C++ version.   

    Below is how the console test of my C++ particle system looks like. Note: it is just used to test and debug the particle system while writing it, this is not the actual test this blog is about.

    I wrote and compiled the project initially in Visual Studio 2010 (for compatibility reason with the tools), then used a tool called make-it-so that will parse the Visual Studio .sln solution and generate a make file out of it.

III - Exposing C++ classes to JavaScript

     Alright, at this step we have a C++ particle system that compiles and can run in console mode as a pure C++ application. We can compile it using the make file produced by MakeItSo - or created by hand if you fancy this kind of thing. However what we want is to be able to instantiate the ParticleSystem from our JavaScript code, so we can really leverage the speed gain from a web application mostly written in js. 

     In order to achieve that, Emscripten offers two different approaches:

1/ Embind: basically you declare the bindings between the C++ class methods and properties and the generated JavaScript objects using the EMSCRIPTEN_BINDINGS macro

2/ WebIDL Binder: you create an extra .idl file that describes the bindings, generate a .js and .cpp files by running a python script from the SDK against the idl and finally compile the project including that cpp file.

    The second option may look like like a lot of extra steps, however this is the one I chose. I felt that the main advantage is that you don't have to modify your initial C++ code by adding macro to each file and link the project to the correct emscripten C libraries, so you can keep your C++ code base intact and keep developing and testing as is. Note that this is also the approach chosen by two major Emscripten C++ ports: box2d.js and ammo.js (Bullet Physics)

     Here are the bindings definition for my project so far:

    Once the bindings are correct, you will generate the glue files by invoking a python script as follow - path will depends on your emsdk location:

python ~/emsdk/emscripten/incoming/tools/webidl_binder.py bindings.idl glue

    This produces glue.cpp and glue.js, you can then create an extra file glue_wrapper.cpp which includes the required headers and glue.cpp, you then add glue_wrapper.cpp to your makefile. This is suggested this way so if you modify your bindings in the future, you can simply re-run the python script without editing any other file in your project. Refer to WebIDL section on the official documentation for more details.

    If everything is done correctly, you should now be able to replace g++ compiler by emcc in the makefile and by running make, it will produce the byte code: ParticleSystem.bc. You can take a look at my custom makefile there. 

IV - Generating asm.js

    We are just one step away from generating asm.js: just run the following command by specifying the glue.js as post-js step, the ParticleSystem.bc from the compilation and also NO_EXIT_RUNTIME=1 option to indicate that even after main has returned, we keep the runtime alive because our JavaScript code will be running the particles. I also comment out all the test code inside the C++ main as it is irrelevant.

emcc -s NO_EXIT_RUNTIME=1 -s release/ParticleSystem.bc --post-js ParticleSystem/glue.js -o dist/asmjs/ParticleSystem.asm.js

    In my project I created the emcc-asmjs.sh script for not having to type the command every time. The output file is valid ES5 JavaScript file ParticleSystem.asm.js that can simply be included in your html using a classic <script> tag. You can take a look at the asm.js test, which is invoking the exported C++ classes, it's pretty close to the C++ code we had originally in main.cpp.

V - Generating Web Assembly

    That's the cherry on the top, by simply adding the BINARYEN=1 option - that's where using the incoming branch of Emscripten matters - you can generate wasm files!

emcc -s NO_EXIT_RUNTIME=1 -s BINARYEN=1 release/ParticleSystem.bc --post-js ParticleSystem/glue.js -o dist/wasm/ParticleSystem.js

In that case it produces several files and loading the script in your html requires a bit more trickery:

 1 <script>
 2   
 3   var Module = Module || {
 4     wasmBinaryFile: '../Emscripten/dist/wasm/ParticleSystem.wasm'
 5   }
 6 
 7   var xhr = new XMLHttpRequest()
 8   xhr.open('GET', '../Emscripten/dist/wasm/ParticleSystem.wasm', true)
 9   xhr.responseType = 'arraybuffer'
10 
11   xhr.onload = function() {
12 
13     Module.wasmBinary = xhr.response
14 
15     var script = document.createElement('script')
16     script.src = "../Emscripten/dist/wasm/ParticleSystem.js"
17     document.body.appendChild(script)
18   }
19 
20   xhr.send(null)
21 </script>

    Testing the wasm can be achieved with the exact same code than for asm.js, I only added a check on Module to see if ParticleSystem object is available as the laoding is asynchronous. It might not be the best approach but reliable enough for now...

VI - Benchmarking the code

    Finally the fun part is to compare how well asm.js and wasm perform against the plain JavaScript code, well my JavaScript code was written in ES6, so it still has to go through a build step to transpile it.

    Asm.js is plain JavaScript so any current browser should be able to load it, wasm is experimental so it has support only in Chrome Canary and Firefox Nightly at this time, with Microsoft Edge coming pretty soon. 

    I created a simple interface using jsoneditor which allows to modify the test configuration. You can tweak the time step, number of particles, number of steps, add some emitters and fields. There is no validation so if you provide invalid or missing parameters, you will probably crash the test. You can also output the particles position to the browser console with dumpParticles set to true, so don't output 10,000 particles over 10,000 steps, you may sit there for a while...

    Loading the wasm on a browser that doesn't support will use a fallback, so the code still runs but ends up being very very slow. You can give it a try but be warned. 

    That's what you can see in your browser console if it can successfully load the wasm file. In Canary it worked straight ot of the install, in Firefox Nightly I had to activate in the config flags javascript.options.wasm: true 

    I created two tests, here are the live versions: ES6 vs ASM.js and ES6 vs WASM and here is a plot of the results I gathered across several browsers, they were using the same default config 1000 particles over 5000 steps:

    Safari comes the very last as far as ES6 is concerned with a huge difference, however the asm.js executes almost the fastest on it with a 42x speed factor increase!

    Firefox Nightly is the one that executes the asm.js code the fastest with an elapsed time of 122 ms. Oddly it doesn't seem to handle wasm very well with a total time of 521 ms, so much higher in comparison

    Canary is the absolute winner of the contest with an execution speed of 121 ms for the wasm version, 12x faster than it runs ES6! However it doesn't handle asm.js as well as Firefox or Safari ...

    That's it for now! I hope you enjoyed, that was a pretty interesting experiment for me so far. The next step will be integrate my particle system asm.js and wasm versions into a Forge Viewer sample and see how much they can increase the FPS of the simulation, so I will definitely blog some more of that in the future.

    The full git project is available at https://github.com/leefsmp/Particle-System with instructions on how to build it. 

 

Translate Referenced Files by Derivative API

By Xiaodong Liang

A 3D model file can be a single file, or a composite file that links with other dependent files. The typical is Inventor assembly (with subassemblies, parts etc), AutoCAD DWG (with Xref), Revit (with linked files). Derivative API supports to translate single file or composite file. 

In the past, the way to configure is using the endpoint of Set Reference. The other blog tells more. It requires the developer to configure the relationship of each child one by one. It was tedious.

With new version Derivative API endpoint, it does not need to set relationship manually anymore. The workflow is now:

1. Package all files in one zip.
2. Upload the zip file to bucket
3. Start translation by the endpoint of Derivative

            POST https://developer.api.autodesk.com/modelderivative/v2/designdata/job

In the parameters, set input.compressedUrn = true and input.rootFilename = the root file name.

 

The Derivative service will detect the relationship and build the hierarchy automatically.

This is a test harness.
https://github.com/xiaodongliang/Forge-Test-Harness-Node.js

And the demo Inventor, AutoCAD, Revit files are available at
https://github.com/xiaodongliang/Forge-Test-Harness-Node.js/tree/master/demo_files

The relevant codes are:

Lmv.prototype.translate =function (urn,iszip,rootfile) {
    var self =this ;

    //default is to export a single file to svf
    var desc ={
        "input": {
            "urn": new Buffer (urn).toString ('base64')// urn of zip file
        },
        "output": {
            "formats": [
                {
                    "type": "svf",
                    "views": [
                        "3d"
                    ]
                }
            ]
        }
    };

    if(iszip)
    {
        //if it is a composite file
        desc.input['compressedUrn'] = true;
        //which one is the root file
        desc.input['rootFilename'] = rootfile;
    }

    console.log(desc);

   //https://developer.api.autodesk.com/modelderivative/v2/designdata/job 
    unirest.post (config.endPoints.translate)
        .headers ({
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'Authorization': ('Bearer ' + Lmv.getToken ()),
            'x-ads-force': true
        })
        .send (desc)
        .end (function (response) {
            try {
                if ( response.statusCode != 200 && response.statusCode != 201 )
                    throw response ;
                try {
                    self.emit ('success', { 'urn': desc.input.urn, 'response': response.body }) ;
                } catch ( err ) {
                }
            } catch ( err ) {
                self.emit ('fail', err) ;
            }
        })
    ;
    return (this) ;
} ;

Forge Data Management API: [Upload, Download, Manage] your Design Data on the Autodesk Cloud

By Philippe Leefsma (@F3lipek)

    My previous Forge-focused blog last week was dealing with the OAuth authentication workflow, in case you missed it here it is:

Landing your Forge OAuth authentication workflow

    If you practiced it a bit, authenticating through the Autodesk OAuth server should now be a breeze for you ;) ... This time we can start having some real fun because we are going to use the actual Forge API's !

    Most likely, the first thing you may want to do is to upload your own models to the Autodesk Cloud, in order to load them at a later time into the viewer or extract some metadata. If for some reason you've got no design data at all, keep reading we've got you covered with a bunch of free sample models ...

I - OSS: Autodesk Object Storage Service

    Let's get started with the easiest part, OSS API. What we now call the Forge Data Management API (see official documentation here) is actually a set of two distinct API's which may be used independently based on what you need to do. If you used the View & Data API in the past, chances are you're probably already familiar with OSS.

    It is a rather basic file storage REST API that lets you host securely any data on the Autodesk Cloud. Typically that's an App-context API, which means you need a 2-legged OAuth token to use it. But for some workflows that we are going to cover in section II of this article, you may use a 3-legged token. The way OSS API works is pretty straightforward:

1. Obtain a valid OAuth token in order to perform authorized REST API calls
2. Create a bucket: a logical storage unit like a folder
3. Upload any file to the bucket (a file is called an object)
4. Download your objects if needed 

    Now here are the tricks: a bucket is created with a specific policy, this defines how long the files are being kept on that bucket.  For info:

• transient: your file remains 24h on the bucket
• temporary: 1month
• persistent: until you decide to delete them 

The bucket itself is never deleted, I just need to emphasis on it because this has been a common misunderstanding in the past! 

    The bucket name has to be lower case, with no special characters and has to be unique service-wide, across ALL the users of the service, not just you. So if you first try the API and attempt to create a bucket named "bucket1" ... unfortunately there are chances that some other developer already owns that name (you will get a 409 - conflict error in such case). So you can either come up with really fancy names or append some guid-like prefix/suffix to your bucket names in order to avoid collisions.

    The object keys can be anything - no special characters though - but need to be unique on a per-bucket basis, otherwise uploading an object with a name that already exists on the same bucket will simply override the resource.

    There also has been often requested how many buckets you can create, how many objects a bucket can contain, how large can be each object... there are no theoretical bounds to the API, sky's the limit. We could advise you create just three buckets (1 transient, 1 temporary and 1persistent) but that's really up to you. If you plan to create multiple buckets based on some workflow, just think about how your logic will scale: creating one bucket per user may not scale nicely once you get a large customer base... 

    If you used the OSS API version1, here are the enhancements for the v2:

• You can now delete an object on a bucket
• Deleting a bucket is doable but NOT for everybody, because that's a dangerous operation, we decided to whitelist users who can do that.
• You can iterate the list of buckets you created from your set of API keys
• Similarly you can iterate the objects stored in each bucket
• You can create signed resources, but I will tackle that in another post (can't get all the fun at once!)

    Below is the implementation of my server-side node service that wraps the OSS API calls. It's pretty straightforward and doesn't do anything fancy. At the time of the writing, I didn't implemented yet the resumable upload that allows you to upload large files by multiple chucks. The reason is that we are working on auto-generated API wrappers for our REST APIs, so I'm waiting for that to be ready. Once the wrapper is available, I simply replace the request calls by the wrapper methods inside the service. The impact on the rest of my server code will be inexistent.

    Using that, the REST API exposed by my server for its client application is just a thin Express wrapper around the service methods. For example below is the "GET /buckets" implementation. For full implementation, take a look there: oss endpoint 

 1 var router = express.Router()
 2 
 3 /////////////////////////////////////////////////////////////////////////////
 4 // GET /buckets
 5 //
 6 //
 7 /////////////////////////////////////////////////////////////////////////////
 8 router.get('/buckets', async (req, res) =>{
 9 
10   try {
11 
12     // obtain forge service
13     var forgeSvc = ServiceManager.getService(
14       'ForgeSvc')
15 
16     // request 2legged token
17     var token = await forgeSvc.getToken('2legged')
18 
19     // obtain oss service
20     var ossSvc = ServiceManager.getService('OssSvc')
21 
22     // get list of bucket by passing valid token
23     var response = await ossSvc.getBuckets(
24       token.access_token)
25 
26     // send json-formatted response
27     res.json(response)
28 
29   } catch (ex) {
30     
31     res.status(ex.statusCode || 500)
32     res.json(ex)
33   }
34 })

You can refer to this page for the official documentation to see how to create a bucket and upload a file to it.

II - A360 Data Management API

    The second set of endpoints within the DataManagement API provides a programmatic access to A360, the Autodesk Cloud at https://a360.autodesk.com. That's a 3-legged OAuth API that let's your application access and manage files of a user once it has been authorized through a web interface. 

    If you don't have an A360 account yet, you will need to signup for one in order to test the API with your data. A set of basic design files will be provisioned automatically to your account upon first sign in.

    The underlying file storage system is based on the OSS API described above but A360 adds an extra layer of features on top of it, such as sharing your data with other users, versioning your files, attaching metadata to it, and many more features to come... It is therefore more complex to use than OSS.

Your data is organized as follow inside A360:

• Hubs: the highest logical data storage on A360. Each user has it's own hub by default but you ca n create additional team hubs and share that with other users
• Projects: under each hub, you have projects, which can be seen as root folders containing your data
• Folders: A logical sub-folder inside a project or another folder
• Items: a file that you uploaded to a project or folder
• Versions: each item may contain one or multiple versions of the file. You can then select programmatically which version you want to access, download or load in the viewer

In order to upload a file to an A360 user account, you have to follow several steps:

1. Your web application needs to obtain a valid 3-legged token by requesting user approval
2. Determine projectId and folderId which identify where on A360 you want to upload the data
3. Create a storage location: basically the API will determine the underlying OSS bucketKey and objectKey you have to use to upload the file
4. Upload the data using OSS API
5. If the file doesn't exist create a new item, otherwise create a new version and add it to the corresponding item

Here is how the implementation of that workflow looks like in my service:

 1 /////////////////////////////////////////////////////////////////
 2 // Upload file to create new item or new version
 3 //
 4 /////////////////////////////////////////////////////////////////
 5 upload (token, projectId, folderId, file, displayName = null) {
 6 
 7   return new Promise(async(resolve, reject) => {
 8 
 9     try {
10 
11       var filename = file.originalname
12 
13       var storage = await this.createStorage(
14         token, projectId, folderId, filename)
15 
16       var ossSvc = ServiceManager.getService('OssSvc')
17 
18       var objectId = ossSvc.parseObjectId(storage.id)
19 
20       var object = await ossSvc.putObject(
21         token,
22         objectId.bucketKey,
23         objectId.objectKey,
24         file)
25 
26       // look for items with the same displayName
27       var items = await this.findItemsWithAttributes(
28         token,
29         projectId,
30         folderId, {
31           displayName: filename
32         })
33 
34       if(items.length > 0) {
35 
36         var item = items[0]
37 
38         var version = await this.createVersion(
39           token,
40           projectId,
41           item.id,
42           storage.id,
43           filename)
44 
45         var response = {
46           version,
47           storage,
48           object,
49           item
50         }
51 
52         resolve(response)
53 
54       } else {
55 
56         var item = await this.createItem(
57           token,
58           projectId,
59           folderId,
60           storage.id,
61           filename,
62           displayName)
63 
64         var response = {
65           storage,
66           object,
67           item
68         }
69 
70         resolve(response)
71       }
72 
73     } catch (ex) {
74 
75       reject(ex)
76     }
77   })
78 }

    The complete implementation is available there: DM Service

    In order to download a file, you first need to determine the available versions and select the version you want, then obtain the OSS objectId of that version and download the file using OSS API.

    Here is how an item versions response may look like, the OSS objectId we are interested is available in relationships.storage.data.id (Line #66). The bucketKey to use would be "wip.dm.prod" and the objectKey "3d249b40-b15d-46a2-b684-001d4534129f.dwfx" 

III - Implementing the UI

    Implementing a good web UI that interacts with your server in order to let your users upload, download and visualize their data is not straightforward at all. I spent a large portion of the development time working on the following control panel that displays the list of all the hubs/projects/folders/items for the signed-in user, the OSS buckets & objects linked to my app account and also lets the user download or upload files either by drag and drop or file picking. Each item in the treeview has also a context menu that provides some actions based on the type of the item. If the item is a design data supported by the viewer, you can double click on it to import it into the viewer.

    I used the following libraries to achieve this control:

• DropzoneJS on the client side  + Multer npm package for node. The setup is very easy and they offer flexible options for customization. For having tried multiple other libraries, I highly recommend this combination!

• The treeview is the one provided by the viewer API: Autodesk.Viewing.UI.Tree and Autodesk.Viewing.UI.TreeDelegate objects. It's a pretty interesting component because it allows to load the data associated with each hub/folder/item asynchronously so you can see the tree will populate progressively but you can start interacting with it directly. You don't have to wait for a huge payload of all your items to initialize the whole tree or load the subfolder only once the user expands them. It would deserve a blogpost on its own to explain all the tricks you can achieve with that control ... You can find the implementation of the tree in Viewing.Extension.Storage.Panel.js

• The TabManager that lets you switch between hubs is a complete custom control. You can find it's implementation in here.

• You can reorder the Tabs by simple drag and drop, this feature is using the dragula library, a must!

• Complete code for that panel is packed into a viewer extension: Viewing.Extension.Storage

    That's it for today! The DataManagemt API official documentation is available here, the complete source code of my ongoing project is there and the live sample runs pretentiously at https://forge.autodesk.io ;) Feel free to try it today with your own A360 account!

    In a next post I will described the work I did with the Model Derivative API which lets you access metadata and properties of your model, convert design data into viewables that can be loaded into the viewer, or export the geometry to different CAD formats.

OSS Resumable Upload - Minimum Chunk Sizes.

The minimum chunk sizes recommendation for the OSS resumable endpoint(s) is a recommendation is 5MB ( and in certain cases, maybe adjusted to be no lower than 2MB in chunk size ).

However, we were not enforcing until now. We will be making changes to OSS to enforce a minimum chunk size ( 2MB chunks ) but we are still recommending a 5MB or greater chunk size.

Only the last chunk (identified by range covering the last byte in the total bytes of the object) will be allowed to be smaller than the 2MB limit.

Show an A360 file in the Viewer

By Adam Nagy

This will likely be improved, but currently in order to show an A360 item in the Viewer you'll also have to use the Model Derivative API on the item - as mentioned by Philippe too here: 
http://stackoverflow.com/questions/37835178/creating-a-viewer-application-with-an-urn-from-autodesk-a360

So first you need to get to the version of the item you want to show in the viewer. You can just follow the steps here to get to the item version you want: 
https://developer.autodesk.com/en/docs/data/v2/tutorials/download-file/

Following the sample's values that you got back in Step 3, you'll see that the returned value contains the items and their versions as well. And the version also contains a storage section under relationships with the id we need:

{
      "type": "versions",
      "id": "urn:adsk.wipprod:fs.file:vf.6bVr4EVDSaOpykczeQYR2Q?version=1",
      "attributes": {
        "name": "House Design.rvt",
        "displayName": "House Design.rvt",
        "createTime": "2016-05-24T19:25:23+00:00",
        "createUserId": "38SCJGX4R4PV",
        "lastModifiedTime": "2016-05-24T19:25:23+00:00",
        "lastModifiedUserId": "38SCJGX4R4PV",
        "versionNumber": 1,
        "mimeType": "application/vnd.autodesk.revit",
        "fileType": "rvt",
        "storageSize": 12550144,
        "extension": {
          "type": "versions:autodesk.core:File",
          "version": "1.0",
          "schema": {
            "href": "https://developer.api.autodesk.com/schema/v1/versions/versions%3Aautodesk.core%3AFile-1.0"
          },
          "data": {}
        }
      },
      "links": {
        "self": {
          "href": "https://developer.api.autodesk.com/data/v1/projects/a.cGVyc29uYWw6cGUyOWNjZjMyI0QyMDE2MDUyNDEyOTI5NzY/versions/urn:adsk.wipprod:fs.file:vf.6bVr4EVDSaOpykczeQYR2Q%3Fversion%3D1"
        }
      },
      "relationships": {
        "item": {
          "data": {
            "type": "items",
            "id": "urn:adsk.wipprod:dm.lineage:6bVr4EVDSaOpykczeQYR2Q"
          },
          "links": {
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/a.cGVyc29uYWw6cGUyOWNjZjMyI0QyMDE2MDUyNDEyOTI5NzY/versions/urn:adsk.wipprod:fs.file:vf.6bVr4EVDSaOpykczeQYR2Q%3Fversion%3D1/item"
            }
          }
        },
        "refs": {
          "links": {
            "self": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/a.cGVyc29uYWw6cGUyOWNjZjMyI0QyMDE2MDUyNDEyOTI5NzY/versions/urn:adsk.wipprod:fs.file:vf.6bVr4EVDSaOpykczeQYR2Q%3Fversion%3D1/relationships/refs"
            },
            "related": {
              "href": "https://developer.api.autodesk.com/data/v1/projects/a.cGVyc29uYWw6cGUyOWNjZjMyI0QyMDE2MDUyNDEyOTI5NzY/versions/urn:adsk.wipprod:fs.file:vf.6bVr4EVDSaOpykczeQYR2Q%3Fversion%3D1/refs"
            }
          }
        },
        ... 
        "storage": {
          "data": {
            "type": "objects",
            "id": "urn:adsk.objects:os.object:wip.dm.prod/977d69b1-43e7-40fa-8ece-6ec4602892f3.rvt"
          },

Now you just have to base64 encode that urn and use it with the Model Derivative API to post an svf translation job for that file:
https://developer.autodesk.com/en/docs/model-derivative/v2/tutorials/prepare-file-for-viewer/

That's it.

Rotating View Cube with JavaScript in the Viewer

By @ShiyaLuo

This is a question we've gotten from partners pretty often. How to programmatically rotate the View Cube?

If you don't want to use THREE.js camera transformations, and just want to call functions to turn the "View Cube" like in a traditional CAD software, there's a function you can call.

In the current version (2.9) of viewer3D, you can call the viewer.setViewCube(face) where viewer is your - DOH - viewer. The options for face are strings front, back, top, bottom, left, right. Calling this function does exactly the same as clicking on the different surface of a View Cube.

Enjoy!

Using Shaders to Generate Dynamic Textures in the Viewer API

By Michael Ge (@hahakumquat)

A week ago, I wrote a post on injecting dynamic THREE.js textures into a viewer scene by creating a plane mesh with a canvas-based material. While the solution works for simple surfaces, it fails for two major reasons:

1. Simply applying a texture to a previously uncolored fragment usually yields an incorrect projection (since the UV mapping coordinates have most likely not been defined).
2. A model's fragment often has complex geometry that cannot be imitated by built-in THREE.js shapes. 

With WebGL shaders, however, we can solve both problems by using pre-existing geometry and defining how each pixel should be rendered.

A Brief Introduction to Shaders

Coming from more of a 3D animation background, shaders seemed like scary, mystical things that always "just worked." But in fact, the concept behind writing shader code is simple. There are only two types of shaders: vertex shaders and fragment shaders. Vertex shaders are programs that define how every point along a surface should be positioned, while fragment shader programs define how every point is colored. Note that a "point" is different from a "vertex" as points span the entire surface while vertices define the boundaries. These programs output vectors based on parameters such as position, the current UV coordinate, etc. Aerotwist's intro to shaders is a great way to get started relatively painlessly using built-in THREE.js functionality.

Generating the Material

 First, we'll use THREE.js's native ShaderMaterial instead of a preset mesh material to texture a fragment. Here, we pass in the vertex shader, fragment shader, and uniform variables. The uniforms include the width and height of the fragment I want to project on, the canvas texture, and a corner variable that is (er, initially was) used for offsetting every point so have nonnegative coordinates. The calculations for _bounds were determined by the genBounds function here:

The color and displacement of every point is then determined by the shaders. 

The Shaders

For my heat map, I wanted every point on the canvas to translate to its scaled position on the actual rooftop, but with a bit of math, shaders offer much more complex and interesting visualizations. 

The final position of any point is determined by the gl_Position variable in the vertex shader. THREE.js magically passes in the position of the current point, position, as well as projection and model-view matrices required to transform the position to the correct perspective. During these calculations, I also determine a vec2 called vUv to pass into the fragment shader.

Now, my original intent when calculating vUv was to project the point onto the xy-plane (bird's eye view), shift it by an offset defined by the minimum corner of the roof, and divide the result by the roof width and height. In theory, this should return a value between 0 and 1, which is the format in which the fragment shader can understand how to apply the texture. The calculation looked something like:

vUv = vec2(abs(projection.x - corner.x) / width, abs(projection.y - corner.y) / height))

But for reasons unknown, it doesn't perform as expected. The code in the gist seems to work, but if anyone can figure out how to sensibly calculate the UV coordinates, I'd love to know.

In either case, a UV vec2 of scaled values between 0 and 1 is passed to the fragment shader. Here, the gl_FragColor simply applies the texture at the UV coordinate specified by vUv.

Setting the Material

The fragment proxy gives us access to a mesh's material, so we simply update the model with our newly created shader material. Here, I access the roof mesh's fragment proxy and recolor the roof to the appropriate material.

Implications

We now have a way to display textures onto meshes that weren't intended to have textures! The possibilities really are endless. Videos can be projected onto any surface, data can be pulled into a scene to create an IoT viewer, even entire webpages can be placed in a scene. The specific use case is up to you, but the idea of taking a texturable asset, importing it into THREE.js, and projecting it via either shaders or standard materials makes the viewer an especially powerful tool.

Landing your Forge OAuth authentication workflow

By Philippe Leefsma (@F3lipek)

    Now that our Forge APIs are available it's time to play with them! But after the initial euphoria is behind, you should think about implementing secure applications in order to protect your resources but also the ones of customers logging to your web application. This starts by getting your OAuth authentication workflow right.

    Before we start I need to mention that I'm far from being a security expert, the information exposed in that blog post is purely extracted from my own experience and the advice I could collect when writing my samples, this should be considered in no way as a recommended approach but rather a suggestion. With that being said, let's get started!

    Our web APIs are using OAuth as authentication mechanism, nothing really fancy here. There are two types of OAuth authentication contexts:

• 2-legged: also called "app-context" where your application (a server, desktop or mobile app) directly request an access token from the Autodesk server and can invoke the APIs with no user intervention. This is the case for the OSS API. Your app can for example create a bucket and start uploading some design there

• 3-legged: also called "user-context" where your app will request explicitly through a web interface (could be a WebView on a mobile or desktop app) a set of permissions from a user in order to access and potentially manipulate his data

    Based on the kind of features you want to provide, you may want one or the other, or both, potentially mixing each approaches. There are however some subtleties in the way you have to request tokens and especially expose that to your client application.

I  2-Legged Token

    Let's start with 2-legged because it's more straightforward: here your app has access to clientId and clientSecret credentials - requested through our dev portal - which have to remain protected on your server or secured within the App - understand some kind of encryption and/or some custom obfuscation. You can share the clientId but may the clientSecret be compromised, another developer would have full access to your data. In such a case you can regenerate a secret on our API portal. Your app will use those credentials to issue a valid token, you also have to pass the scope which can be a single value or a space-separated, url-encoded string in case you request multiple scopes, eg data:read data:write (see my method requestToken in the sample below). Once a token is acquired, you may use it on your server to access the API or expose your own API endpoints for your client app, so a user will be able for example to upload his file to a bucket. In that case it's important that this data:write token remains hidden on your server because otherwise you expose the possibility to a bad intentioned user to mess up with all your data.

    If you want to let a user load his model in the viewer on a web page, you need to expose an endpoint that returns a data:read token, so in that case you can request a new token with only data:read scope and expose that as an endpoint, in the case of my sample this is /api/forge/token/2legged 

    A 2-legged token expires after a certain time - expires_in field of the response - you can either keep refreshing the token and always keep a valid token on your server, or request a fresh token for each new operation. Alternatively implement a retry mechanism that will request a token only if the current one is expired at at the time of the call - if you get an 'Unauthorized' error basically. All approaches are valid and depend on the kind of feature you are providing and how often your app is going to require tokens I would say.

II  3-legged Token

    3-legged is a bit more tricky because here issuing a valid token depends on user authentication so at some point you need to prompt the user for his Autodesk credentials in conjunction of the API keys that you have stored on the server. You also need to specify scopes and this will explicitly be shown to user on the login page so he knows the extends of the permissions granted to your app. 

 

    A 3-legged token also has an expiry period, but unlike the 2-legged workflow where you can simply request a new token, in 3-legged you would need to request user credentials again to issue a brand new token. For that reason each token response contains a refresh_token field that is a code you can use with a specific endpoint to request a new valid 3-legged token without user interaction. For that reason it is very important that you keep that refresh code securely on your server and do not share it with the users or expose it in any way to the outside. 

    Similarly to a 2-legged token, in case you want to use the viewer to load user models, you need to expose an endpoint that would let you client application obtain a data:read token, without exposing a full-privilege token. You do not want to ask a user to log twice in order to obtain a second read-only token, so in that case you need to use the refresh_token field of the initial response in order to request what we can call a "downgraded token" that's a token that is requested from the refresh code but with a reduced set of scopes. The reduced scopes can only be a subset of the initial token scopes. The downgraded token response will also contain a new refresh_token code, you need to carefully store that because each refresh code can only be used once. You need to use that refresh code also to refresh the full-privilege token.

    Below is the implementation of my Forge sample relevant to OAuth workflow and tokens management. I am splitting the code into the implementation of the endpoints and a utility called ForgeSvc (Forge Service) which allows some decoupling and flexibility in case the service has to be used by other endpoints or other services within the App. I find the approach pretty convenient even if it requires more files and more code than direct implementation in the endpoints. It definitely scales better once the codebase grows and the app becomes more complex.

Here is the OAuth workflow and secure forge token endpoints: 

    And here is the implementation of the Forge Service which keeps tracks of 3-legged and 2-legged tokens. It worth mentioning that it is NOT a good idea or secure approach to store tokens into the session properties (in your node.js code for example: req.session.token = 'xxxxxxx') because this can be hacked easily. At the moment my service is using a simple in-memory storage which can be replaced by a more sophisticated persistence mechanism later on without breaking the endpoints:

    The complete source code of that sample is available there but keep in mind that, like our Forge API's, it is a work in progress... A live sample is available at https://forge.autodesk.io

Finally for more info and step-by-step tutorials on Forge OAuth, please refer to the official documentation.

OAuth Server Maintenance

By Stephen Preston

(Updated with maintenance date).

We plan to apply an update to the Forge OAuth server on July 30th 2016 (at approximately 4pm PDT). When the upgrade takes place, all 2-legged Access Tokens will be invalidated and will have to be refreshed. In addition, the duration for 2-legged Access Tokens will be temporarily reduced from 24 hours to 30 minutes the day before the upgrade (and reinstated back to 24 hours afterwards).

If you have correctly implemented seamless Access Token refreshing in your code (as you should have done :-) ), then you don't need to take any action. However, if you have not, or if you are making an assumption that the Access Token duration is always 24 hours, then you should update your application now to prevent it failing.

3-legged OAuth is not affected by this update.

Projecting Dynamic Textures onto Flat Surfaces with Three.js

By Michael Ge (@hahakumquat)

First and foremost, the 3D Viewer is designed to display static 3D objects, but this is not to say that applications of the Viewer cannot have dynamic elements within it!

So far, most of the extensions on our blog have dealt with manipulating elements in the viewer to return static changes, but with relatively simple injections of Three.js code, it's possible to quickly turn a single-state model into a data-driven, dynamic 3D simulation.

The extension I've developed is a heatmap projection onto a 3D model of a building. While the input "data" is currently random, the modular code makes it easy to substitute these randomly generated data points with real sensors in an actual building.

To visualize this data, I used mourner's simpleheat.js library to create a heatmap on a canvas element. From there, I created a Three.js plane and projected the texture onto the plane, masking out the shape of my desired rooftop. Several code snippets are taken from Philippe's examples, including getting the bounding box of a fragment and adjusting fragment positions. Overall, it's a simple process with plenty of documentation and resources, and with a few minor changes here and there, you should be able to achieve the same effect in any scene.

With that said, let's take a look at the actual code. The extension can be broken up into four main sections: Viewer functions, heatmap initialization, material initialization, and application of the material onto a mesh.

Viewer Functions

////////////////////////////////////////////////////////////////////////////

    /* Private Variables and constructor */ 
    
    // Heat Map Floor constructor
    Autodesk.Viewing.Extension.call(this, viewer, options);
    var _self = this;
    var _viewer = viewer;

    // Find fragmentId of a desired mesh by selection_changed_event listener
    var roofFrag = 1;
 
    // Settings configuration flags
    var progressiveRenderingWasOn = false, ambientShadowsWasOn = false; 

    // simpleheat private variables
    var _heat, _data = [];
    // Configurable heatmap variables:
    // MAX-the maximum amplitude of data input
    // VAL-the value of a data input, in this case, it's constant
    // RESOLUTION-the size of the circles, high res -> smaller circles
    // FALLOFF-the rate a datapoint disappears
    var MAX = 2000, VAL = 1500, RESOLUTION = 10, FALLOFF = 30;

    // THREE.js private variables
    var _material, _texture, _bounds, _plane, Z_POS = -0.1; //3.44 for floor;
    
    ////////////////////////////////////////////////////////////////////////////
    
    /* Load, main, and unload functions */

    _self.load = function() {

        // Turn off progressive rendering and ambient shadows for nice look
        if (_viewer.prefs.progressiveRendering) {
            progressiveRenderingWasOn = true;
            _viewer.setProgressiveRendering(false);
        }
        if (_viewer.prefs.ambientShadows) {
            ambientShadowsWasOn = true;
            _viewer.prefs.set("ambientShadows", false);
        }
        
        _bounds = genBounds(roofFrag);        
        _heat = genHeatMap();
        _texture = genTexture();
        _material = genMaterial();
        
        _plane = clonePlane();
        setMaterial(roofFrag, _material);
        
        animate();
        console.log("Heat Map Floor loaded.");
        return true;
    }
    
    _self.unload = function() {

        if (progressiveRenderingWasOn)
            _viewer.setProgressiveRendering(true);
        if (ambientShadowsWasOn) {
            _viewer.prefs.set("ambientShadows", true);
        }
        progressiveRenderingWasOn = ambientShadowsWasOn = false;
        
        delete _viewer.impl.matman().materials.heatmap;
        _viewer.impl.scene.remove(_plane);
        
        console.log("Heat Map Floor unloaded.");
        return true;
    }
    
    // Animation loop for checking for new points and drawing them on texture
    function animate() {
        requestAnimationFrame(animate);
        _heat.add(receivedData());            
        _heat._data = decay(_heat._data);
        _heat.draw();

        _texture.needsUpdate = true;
        // setting var 3 to true enables invalidation even without changing scene
        _viewer.impl.invalidate(true, false, true);
    }
    
    ////////////////////////////////////////////////////////////////////////////

    /* Geometry/Fragment/Location functions */

    // Gets bounds of a fragment
    function genBounds(fragId) {
        var bBox = new THREE.Box3();        
        _viewer.model.getFragmentList()
            .getWorldBounds(fragId, bBox);
        
        var width = Math.abs(bBox.max.x - bBox.min.x);
        var height = Math.abs(bBox.max.y - bBox.min.y);
        var depth = Math.abs(bBox.max.z - bBox.min.z);

        return {width: width, height: height, depth: depth, min: bBox.min};
    }

The scene will constantly be updating with new heatmap data, so we'll need to keep track of several private variables for the heatmap and plane. In addition, the constant updates yield rather ugly flickering with progressive rendering and grainy ambient shadows, so we'll also keep track of the settings' states before the extension is enabled so that we can revert to the original state.

The load function, when run on initialization, disables these settings, creates the material with the canvas, and projects the material onto the rooftop. As expected, unload undoes such modifications. 

animate begins a requestAnimationFrame() loop that adds any received data from sensors (or in my implementation, random data), creates a data falloff effect over time, and tells the viewer to update itself with an updated texture. It's important here to note that the invalidate() call has a third parameter which, when set to true, updates overlays. This is critical to getting the texture overlay to update correctly.

Heatmap Initialization

///////////////////////////////////////////////////////////////////////

    /* Heatmap functions */
    
    // Starts a heatmap
    function genHeatMap() {

        var canvas = document.getElementById("texture");
        canvas.width = _bounds.width * RESOLUTION;
        canvas.height = _bounds.height * RESOLUTION;

        return simpleheat("texture").max(MAX);
    }

    // TODO: Replace with actually received data
    // returns an array of data received by sensors
    function receivedData() {

        return [Math.random() * $("#texture").width(),
                Math.random() * $("#texture").height(),
                Math.random() * VAL];
    }

    // decrements the amplitude of a signal by FALLOFF for decay over time
    function decay(data) {

        // removes elements whose amlitude is < 1
        return data.filter(function(d) {
            d[2] -= FALLOFF;
            return d[2] > 1;
        });
    }

mourner's simpleheat.js makes it easy to create a heatmap, taking in data with a Cartesian coordinate and amplitude, and outputting a circle with the designated location and color intensity. 

genHeatMap simply creates a canvas to store the heatmap data, returning the generated simpleheat object.

Every time an animate function is called, the heatmap will add data from receivedData. Sensory input data in the format of a size-3 array could replace the currently random generation of data points.

For this experiment, I wanted to remove old datapoints. As a result, I created a decay function that lowers the amplitude values of all elements in the dataset over time, removing them once they become negligible, however it's possible to aggregate data over time, porting that information over from a database.

Material Initialization

Now that we have a dynamically updating canvas, we can apply it as a texture to a created Three.js plane:

    ///////////////////////////////////////////////////////////////////////

    /* Texture and material functions */
 
    // Creates a texture
    function genTexture() {
 
        var canvas = document.getElementById("texture");
        var texture = new THREE.Texture(canvas);
        return texture;
    }

    // generates a material
     function genMaterial() {

     var material = new THREE.MeshBasicMaterial({
         map: _texture,
         side: THREE.DoubleSide,
         alphaMap: THREE.ImageUtils.loadTexture("mask_crop.png")
     });
     material.transparent = true;

     // register the material under the name "heatmap"
     _viewer.impl.matman().addMaterial("heatmap", material, true);
 
     return material;
 }

genTexture creates a Three.Texture from the canvas that is mapped to the basic material. In order to exclude parts of the canvas that are outside the roof area, we also use an alpha mask like the following:

Applying the Material to a Mesh

We have the material ready to go, so now it's just a matter of applying it to the proper face. 

 ///////////////////////////////////////////////////////////////////////

 /* Rendering the heatmap in the Viewer */

 function clonePlane() {

     // To use native three.js plane, use the following mesh constructor    
     geom = new THREE.PlaneGeometry(_bounds.width, _bounds.height);
     plane = new THREE.Mesh(geom, _material);
     plane.position.set(0, 0, _bounds.min.z - Z_POS);

     _viewer.impl.addOverlay("pivot", plane);
 
     return plane;
 }

We create a geometry of the roof's width and size and apply the material. Finally, we move the original plane to the desired location and insert it into the scene as an overlay.

 I also noticed that simply calling the addOverlay function without modifying the simpleheat.js code led to circular artifacts around the data points. This is an easy fix, however. Simply go into the draw function in simpleheat.js, and after the clearRect() function is called, draw a nearly completely transparent rectangle over the entire canvas:

        ...
        ctx.clearRect(0, 0, this._width, this._height); 

        // include the following section
        ctx.fillStyle = "#FFFFFF";
        ctx.globalAlpha = 0.01;
        ctx.fillRect(0, 0, this._width, this._height);
        ctx.globalAlpha = 1;

 

Here's the full source code for the extension:

And here is a link to the project demo.

Hope you like it!