THIS API IS IN BETA AND THIS DOCUMENTATION IS INTENDED FOR BETA USERS ONLY
Tutorial
Before You Begin
- Register an app, and make sure you select the Data Management and Data Exchange APIs.
- Acquire a 3-legged OAuth
token with
data:createdata:readanddata:writescopes. - Verify that you have access to the Autodesk Construction Cloud (ACC).
1. Using the code
Create the app
Create a new C# .Core console application in Visual Studio. For sample purposes, we’ll use the name GeomUtilsTest. At create time, you’ll have a console application that looks as follows.
using System;
namespace GeomUtilsTest
{
class Program
{
static void Main(string[] args)
{
Console.WriteLine("Hello World!");
}
}
}
Perform the following steps to get your project ready for this sample.
- Add several “using” statements at the top of your code to prepare for this sample.
- using Autodesk.GeometryUtilities.SDK;
- using System;
- using System.IO;
Create and authenticate the client
To begin, create the geometry exchange client. This class is part of the SDK and serves as the main interface.
var client = new Autodesk.GeometryUtilities.SDK.Client();
Next, we need to set the 3-legged access/authentication token that the SDK uses to communicate with the ACC. The client contains a context object where the authentication token is stored for all subsequent operations. In this sample, we prompt for and read the token from the console.
Console.Write("Enter a 3-legged Forge access token: ");
client.Context.AuthToken = Console.ReadLine();
The full creation and authentication of the client should now read as follows:
Note: All SDK calls should be wrapped in a try/catch block.
try
{
var client = new Autodesk.GeometryUtilities.SDK.Client();
Console.WriteLine("Enter a 3-legged Forge access token: ");
client.Context.AuthToken = Console.ReadLine();
...
}
catch (Exception ex)
{
...
}
Set the output directory
By default, output from the SDK goes into a directory named “GeometryBinaryOutput” that resides in the working directory of the project. This is typically set by the SDK user. For this example, we’ll create a folder named “exchangeModels” in our project directory and set that as the output directory on the client context.
string modelsDir = Path.Combine(Directory.GetCurrentDirectory(), "exchangeModels");
if (Directory.Exists(modelsDir)) Directory.Delete(modelsDir, true);
Directory.CreateDirectory(modelsDir);
client.Context.OutputDirectory = modelsDir;
Note that Directory.GetCurrentDirectory() returns the working directory for the project in Visual Studio which we set to $(ProjectDir) in our project setup.
Download the Geometry Assets
With the application authenticated, we can perform the operation. The main operation currently available in the client is to find the geometry assets in the specified exchange container on the ACC and download them as STEP files. To do that, you need the exchange ID or the urn of the exchange container. In this tutorial, we use the exchange urn.
In this sample, we use code to query the exchange container urn from the user. This is not a realistic example but serves our purpose. Assuming that you have the urn, you can make the following call to download the assets from the container and save them as STEP files.
int howMany = client.DownloadGeometriesAsSTEP(exchangeFileUrn);
In the background, the code queries the ACC for all assets contained in the data exchange container identified by the input urn. The assets are all queried for type and only assets that are geometry are downloaded as binary files. The downloaded binary files are then converted to STEP with ATF and the number of successful downloads/conversions is returned to the caller.
Note: The “DownloadGeometries” method also takes an optional “AssetFilter” object. You can use the asset filter to limit the results by specifying a single asset id to download or by putting a limit on the number of assets that are downloaded.
2. The Output
After performing a download using the SDK, you can find the requested geometric assets in the folder you specified as the output folder in your SDK call. The files are named using the asset id. For each asset, there is a “stp” file which contains the STEP representation of the asset data. In addition there will be a file named “AssetData.json” that will contain some additional data for each of the assets downloaded in the last download operation. That data will look something like the following (using a download of two assets as an example).
[
{
"AssetId": "2EFD00DE380A8BC14FB195701B391C2E57FC6AB1",
"DisplayLengthUnit": "autodesk.unit.unit:feet-1.0.1",
"LengthUnit": "autodesk.unit.unit:centimeters-1.0.1",
"Transform": "[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]",
"ComponentName": "Generic Models__Model Text__12\" Arial__2487"
},
{
"AssetId": "385E8091D6437F011430DE796739256237B161BA",
"DisplayLengthUnit": "autodesk.unit.unit:feet-1.0.1",
"LengthUnit": "autodesk.unit.unit:centimeters-1.0.1",
"Transform": "[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]",
"ComponentName": "Roofs__Basic Roof__Generic - 4\"__2481"
}
]
The properties are:
- AssetId - the asset id for the geometric asset in the exchange.
- DisplayLengthUnit - the length unit from the original file used to create the exchange.
- LengthUnit - the length unit stored in the geometric asset and resulting STEP file.
- Transform - a modeling transform applied at the asset level.
- ComponentName - the geometry asset component name.
This data is informational only. The Transform property does NOT represent the location of the asset in a larger assembly. That information must be queried from instance level assets in the exchange through the FDX SDK directly.
3. Logging
In addition to the STEP files, the output folder also contains a log file. The default name for the log file is “GeomUtilsLog.txt”. Extensive logging is done during SDK operations. If things don’t go as planned, this is a handy debugging tool. Several options exist for logging including; the level of logging done, the log target, and the filename if the target is “File”. These options are all available as properties on the client context and are as follows:
Level of messaging:
- LogLevel.Debug - detailed debugging messages.
- LogLevel.Info - status report messages (default).
- LogLevel.Warning - messages showing something went wrong but workflows can still continue.
- LogLevel.Error - disruptive error messages.
Logging targets:
- LogTarget.File - log messages to a specified file (default = “GeomUtils.txt”) (default)
- LogTarget.Console - log messages to the console.
Logging options can be set with the static properties on the Client class as shown in the following examples.
- Client.LogLevel = LogLevel.Debug;
- Client.LogLevel = LogLevel.Error;
- Client.LogTarget = LogTarget.Console;
- Client.LogTarget = LogTarget.File;
- Client.LogFile = @”C:\TEMP\MySDKLog.txt”;
By default, level is set to LogLevel.Info and the target is a LogTarget.File named “GeomUtilsLog.txt” in the output folder.
Sample Code
The complete sample code for this page is listed below.
using Autodesk.GeometryUtilities.SDK;
using System;
using System.IO;
namespace EarlyTesters
{
class Program
{
/// <summary>
/// Main entry point.
/// </summary>
/// <param name="args">Command line arguments.</param>
static void Main(string[] args)
{
try
{
// Create the geometry exchange client from the SDK.
//
var client = new Client();
// Query an exchange id or container urn from the console.
//
Console.Write("Enter an exchange ID or file URN: ");
string exchangeIdOrFileUrn = Console.ReadLine();
if (string.IsNullOrWhiteSpace(exchangeIdOrFileUrn))
return;
// Query a 3-legged access token from the console and set it on the client context.
//
Console.Write("Enter a 3-legged Forge access token: ");
client.Context.AuthToken = Console.ReadLine();
if (string.IsNullOrWhiteSpace(client.Context.AuthToken))
return;
// Create the full path to the output folder under the current working directory
// named "exchangeModels" and set it as the output folder on the client context.
//
string modelsDir = Path.Combine(Directory.GetCurrentDirectory(), "exchangeModels");
if (Directory.Exists(modelsDir)) Directory.Delete(modelsDir, true);
Directory.CreateDirectory(modelsDir);
client.Context.OutputDirectory = modelsDir;
// Call the method on the geometry exchange client to download all of the geometric
// assets as STEP files putting the results into the output folder.
//
Console.WriteLine("Getting geometry STEP assets for: {0}", exchangeIdOrFileUrn);
int howMany = client.DownloadGeometriesAsSTEP(exchangeIdOrFileUrn);
Console.WriteLine("Found {0} geometry assets.", howMany);
}
catch (Exception ex)
{
Console.WriteLine(ex);
}
}
}
}
