Unleash the Power of Design Data with Autodesk Forge API

MIKAKO HARADA: Hi, everybody. My name is Mikako Harada from Autodesk. I'm from Developer Technical Services Team. Today, I'm going to talk about the power of design data using Forge API.

But first, safe harbor statement. This presentation may include a forward-looking statement. This is not the promise, and then it may change in future. So, please, do not make a purchase decisions based on those statements.

And the agenda. So, today, in this recording, I'm going to focus on the Model Property API. At the on-site event in September, I also intended to include Data Exchange API, which is currently in beta, and then Parameter Services API, which is still in pipeline. So I just wanted to make sure people who are watching this is aware of this.

So, first, Model Properties API. Before we talk about what the Model Property API does and how to use it, let's first look at the lifecycle of design data using Docs today-- Autodesk Docs or BIM 360 Docs. Currently, design data or a file is created using authoring tools, typically, desktop products such as Revit and AutoCAD.

And design file is then uploaded to Docs. Uploaded file automatically translated by Derivative Services. As a result, you have a set of variables with a geometry data. At this point, it also generate so-called property DB or property database.

And using the Forge viewer, it allows you to display those design data in human-readable format. When changes are made to these models, a new version of file is produced and uploaded to the Docs as a new version of the files, and the process is repeated.

At this point, what we are interested in is those designed data that are extracted from the model or files. Most of you probably have seen this one before. And this is the viewer we know right now. And this is a view of property DB that many of you are familiar.

And then in that Property pane on the middle, you see the properties data. This is the model data we are talking about. And when the file is converted to SBF or SBF2-two, which is a viewable format, model data is stored inside of the Docs.

And then [INAUDIBLE] we start with a category, name, type, such as the string, and Boolean, and so on. And then, optionally, the unit of measurement when the value is measurable.

So the Model Properties API was released early this year. The API works with the models in ACC, Autodesk Construction Cloud, Unified Product, and BIM 360. And data center in the US and European data center are both supported. This one is built on top of SVF2 Again, this is a viewable format.

And this one is enhanced-- this is the enhanced version of the viewable format. And then Derivative Service produces. It extends the property data for analysis of BIM models.

There are two main functions. One is an index. This allows us to query and filter properties over SVF2 object. And the second one is a diff. This one is also use index data. Plus, it has an ability to compare two versions, in this case, two versions from the same models, not the two versions of different models.

So this one is used in a product. So, for instance, the image shown on this side is actually from the product feature, change analysis feature in the design collaborations. There are also a feature release in pipeline.

So there are two features we are expecting. One is the asset integrating with the models, and this one is currently in beta. And then, also, model coordination side with a model breakdown for crash analysis. This slide also expected.

So supported file format for basic property indexing is that it supports any files that is supported by SVF2. And the diff side-- the file type supported by diff one is the one listed here. In case of this, file type need to have a uniquely identifiable ID. So, currently, it's supported by RVT, DWG, and NWC.

This is Navisworks-based files. And this one is created from-- exported from Revit and then AutoCAD verticals. And then, also, the IFC exported from AutoCAD Architecture, MEP, and also Civil 3D, and ARCHCAD, Revit, of course, and then MigiCAD and Tekla.

So the next one-- next, we will show you the three example applications using Model Properties APIs. The first one is a filter element and then partial modeling load. This sample demonstrate filtering element by properties, which can be geometric properties, such as length and height.

And filter condition is defined as a binary expression forms and can be combined by AND/OR. The result to be visualized from using Forge viewer. Note that this Model Properties API itself doesn't come with a viewer. That you can use Forge viewers visualize it.

So in this example, first, he shows filtering with a floor element in one level. So, now, he's choosing element and third floor and query. And then loading on the model. As you can see that the model is only chosen for the third floor.

And he's adding one more filter categories. And, now, it's only show the windows. As you can see, it is possible to filter only the ones you are interested in. And then the second one-- another model, a second model-- in this one, once you have indexed, you can have a different query.

For instance, in this case, category ducts. And this is greater than six. And another category-- now, it's the duct fitting. And then classification is the supply air. So then, now, you run the query, you see the curated element is displayed here.

So the next version is compare coding diff functions. And it uses-- it compares the two files and then identify the differences. So coding diff functions, now.

And the green shows the element which is added. And then red shows the element which is removed from the left side. And then the blue shows the ones we just modified.

And then, in this case, he's looking at added one, removed one. And then--

Now, he's taking the changed element. So you can check if the property has changed And what kind of element of the property has changed. And, now, you can see it say, elevation from the level is different.

And then he is, actually, tried to compare the elevations. So elevation is now 10.666 on the left side. And the right side is 8.75.

As you can see, it has been changed. So those data are very difficult to look just by looking at this. But if you can see the detail, then you can see the differences more clearly.

So the third example-- the two sample we have shown demonstrate only the filter and then diff of two main functions. And then third one is putting this functionality in certain context. And in this case, the user context of integration with the cost and then takeoff.

It identified the changes in takeoff items and then compared the current and then previous version of the model and then visualize differences in the viewer. So, for instance, this is a UI-- UI of the takeoff.

And you take-- and then this is the one with the application. It goes a little bit fast. But this one takes the information from the takeoff. And then, in this case, this is the first time, so there is no change.

And you take the package information and then put it in the cost module. And then, now, you see the cost UI-- currently, it's empty. But if you refresh, you see the information coming from takeoff plus some additional data added in the custom application is shown here.

So, next, the second time, when you are looking at the takeoff, you can see what kind of model information has been updated in the UI. So the ones with the yellow mark is the ones which signal something has changed. But it actually doesn't show more than just the signaling with this yellow mark.

And then using this custom application, you can dig into more detail and then compare the versions. So, in this case, you can see the window has been changed by using this and embedding this-- the comparison features-- just like we saw in a previous example.

So you can see, in this case, that it simplifies to make it clear what we are doing. But you can see the changes listed on the bottom right side. And then you can continue like this and then put it back to cost information, for instance.

So, next, let's take a look at how this one works. So, as we mentioned earlier, Model Properties API make use of SVF2. And many of you are probably familiar with the workflow when the modifier is uploaded to Autodesk Docs or BIM 360 Docs, either by UI, Desktop Connector, or API, the file is automatically translated to SVF and SVF2.

And then translation-- since the translation is automatically triggered, user doesn't notice. And viewable and then property database is automatically generated, at that point. And so this is data that contains rich design data.

So a Model Properties API-- an additional area to this workflow. The first step is to create the indexing, meaning that you can search those properties. And then Index API generate three downloadable JSON files-- manifest, field, and properties.

And then, after that, we can run the query. The result file will be a JSON file and matching to the query filters. There are four resources generated during this process-- Manifest Files, which is JSON file containing the indexing or query detailing the seed file, SVF property DB used to generate indexing loads.

And other three files are all the Newline-delimited JSONs. We put it as NDJSON. And fill the contained definition of the unique field or property types extracted from the index or query.

And third one-- properties-- contain the raw object properties values for the indexing. And then results contain the object properties resulted from the query executed.

There are eight endpoint for each index and then diff functionalities. They are very similar. And, here, I'm looking at the indexing side.

First, to create a basic index we call a batch status method. This allows you to check the status of one or more file version indexing. And this one is a so-called lazy, meaning that if indexing job for the file has not been executed, service will automatically start.

But once it's executed and it already exists, it uses a cached data. So the cached data will be kept for 30 days since last-used. And the second endpoint is used to call the progress. And response for both the endpoint would be identical.

And then here's example of creating basic indexing using a batch status. This specify one-version URL. And then response include the index ID and states which show the progress progressing right now and then the retry timing.

And then, in this example, process is still running. So the starts and then three URL toward the bottom are all showing as a null. And after waiting a little bit, then, normally, the process complete. And here is an example of pulling for progress.

And then, here, the state is shown as finished. And then toward the end, you can see three URL. And these are downloadable for manifest, and field URL, and then properties URL. And you can also see the start-- the number of the objects.

OK. And then, optionally, you can also download those three-- manifest, field, and properties-- using the composing endpoint, like shown here. Yeah, so during the development, you most likely needed to use this in order to understand the properties specific to your own file format.

And then here is the example showing how manifest file looks like. And it includes seed file information, lineage, and URN. And the information about the SVF2 property database is also there. And viewable information, too.

And this example shows two viewables called 3D and new constructions. And if you are ready to use, as you probably can guess, this one is coming from Revit files. And then, finally, toward the bottom, stacks from the start with the number of object. And then index files-- the byte size is included there. So there are quite a lot of information you can find.

And then, here, the example of index field. Each row represents a fields used for index-- key, categories, data type-- such as doublets and strings-- and the name of the field, and then unit of measurement. In case there is a measurable one, you have this value there.

And here is how the basic property looks like when-- and this line is formatted for the readability. It includes the ID of related objects, and these two properties, and keys, and body pair, and property hash, and the properties ignored when calculating a hash, and then geometry hash, bounding box information, and then, finally, viewable containing the object.

Once index has been successfully created, it can be queried. And index queries are described using a custom JSON schema, which is converted to the filter expressions, and they are applied to the index line by line. And difference guide on the dev portal include the comprehensive query language references which describe how to write the queries with an example using this JSON schema.

And here example queries. This is to get the viewable the Revit category with the family and type. Left side is the index query we use, which is equivalent to the S3 SQL shown on the right side.

The final step in the process is to use the curated result URL to download the indexing rules which matches the submitted query expressions. This line-delimited JSON result row are subset of property index rows and then have exactly the same format, as a result of the indexing.

So the second feature, diff-- so diff index rows returned the-- for diff, step the same as a basic index, but that we specify two version URL to compare, of course, since we are comparing two versions. And then start will have an add, remove the modified information.

So diff index row returns the compressed GDP information. And then this is an example of diff indexing row. So it's formatted as a single JSON document, again, to make it easier to read.

And then I just want to emphasize that we have a type object changed at the top. And then we also see prev, so this means previous. So you can see the object embedded in the current row with this key with different values.

So this table summarizes the list of fields included in the index row. And ones within yellow-- basic index. And then using diff in addition to the basic index, you would have the similar set of prev or a previous version-- version, and type, and then change types.

And here is a list of a custom JSON abstract syntax. This would be converted to a SQL-like format in-- SQL-like S3 Select in AWS.

So the developer resources-- so for more information, on the please take a look at the documentation in the dev portal. Model Properties API has a very good, comprehensive explanation. Engineering team did a very good job. So please refer to it.

And samples shown-- all three samples so today all available as a code sample on GitHub. So there are several blog posts by Xiaodong Liang, as well. So you can search on the dev portal site, as well.

And I just wanted to acknowledge the engineering team and then my team for the hard work preparing these APIs and then also presentations. And thank you very much.