Design Automation tutorial review #98
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,9 @@ | ||
| # Define an Activity | ||
|
|
||
| Activity is the specification of an action that can be executed using a specified engine. It specifies: the number of input and output files, the AppBundle and an entry-point to use. | ||
|
|
||
| In this tutorial sample, the activity has 2 inputs (file & JSON data) and 1 output (file). | ||
|
|
||
| > It's worth mentioning again the Design Automation documentation for [entities](https://forge.autodesk.com/en/docs/design-automation/v3/developers_guide/field-guide/), where you can see the relation between them in [Entity Relationships](https://forge.autodesk.com/en/docs/design-automation/v3/developers_guide/field-guide/#entity-relationships) | ||
|
There was a problem hiding this comment. thinking if this image help or not... my perception is that is too complicated, considering this is a basic tutorial, but open to suggestions. There was a problem hiding this comment. I agree it can be confusing to show this at the beginning of the tutorial, but this comment is done in purpose in an advanced moment of the tutorial, when creating the Activity, to clarify possible doubts with the API entities (Activity vs Engine vs Workitem vs AppBundle) and the relation between them. At this point, introducing the concept of activity, the rest of the items have to be clear, because in terms of logic-relation is the one which unites them :-) There was a problem hiding this comment. maybe move that as a "learn more" in the first paragraph? so we keep the 1st paragraph as general info, the 2nd as the call to action. |
||
|
|
||
| Choose your language: [Node.js](designautomation/activity/nodejs) | [.NET Core](designautomation/activity/netcore) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,23 +1,22 @@ | ||
| # Prepare an AppBundle (plugin) | ||
|
|
||
| At this section we will create a basic plugin or AppBundle that searches for the Windows in the scene model tree and updates the `width` and `height` parameters of it, saving the resulting file as a new file. | ||
|
|
||
| Design Automation uses .bundle just like the Autodesk App Store. For it, a `PackageContents.xml` descriptor file will be created and ZIP together with the `DLL` and other possible required files. For detailed information on how to create them, please visit [Autodesk App Store Developer Center](https://www.autodesk.com/developer-network/app-store). The created ZIP AppBundle file will be uploaded. | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - **7zip**: use to create the .ZIP with bundle files, please install [from here](https://www.7-zip.org/). This tutorial assumes **7zip** is installed on the default folder: _C:\Program Files\7-Zip\7z.exe_. | ||
|
|
||
| #### Additional prerequisites | ||
|
|
||
| For the next session you can use the pre-build plugin. Or if you decide to build it, you will need: | ||
|
|
||
| - **Visual Studio**: Visual Studio 2017 or newer is required, please visit [this link](https://visualstudio.microsoft.com/vs/). | ||
|
|
||
| - **AutoCAD, Inventor, Revit or 3ds Max**: In order to develop, compile, test and debug your Design Automation plugin, you will need the respective application installed: [AutoCAD](https://www.autodesk.com/products/autocad/overview) | [Inventor](https://www.autodesk.com/products/inventor/overview) | [Revit](https://www.autodesk.com/products/revit/overview) | [3ds Max](https://www.autodesk.com/products/3ds-max/overview). | ||
|
|
||
| *** | ||
|
|
||
| The **Engine** is the Autodesk application where your plugin or App will run. Choose the engine you will use: | ||
| [AutoCAD](/designautomation/appbundle/engines/autocad) | [Inventor](/designautomation/appbundle/engines/inventor) | [Revit](/designautomation/appbundle/engines/revit) | [3ds Max](/designautomation/appbundle/engines/max) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| # Create and upload AppBundle | ||
|
|
||
| Now that the ZIP AppBundle is ready, let's upload it to Design Automation. | ||
|
|
||
| Choose your language: [Node.js](designautomation/appbundle/nodejs) | [.NET Core](designautomation/appbundle/netcore) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,7 +11,11 @@ Remember that for Design Automation, there should be no UI or prompts that canno | |
|
|
||
| ## Create a new .NET project | ||
|
|
||
| Right-click on the solution, and then **Add** >> **New Project**. Select **Windows Desktop**, then **Class Library** and, finally, name it `UpdateMAXParam`. | ||
|
|
||
| You will then need to reference the Autodesk.Max.dll managed assembly (3ds Max .NET API core module). This module is found in the 3dsmax.exe folder and when referencing, make sure to turn off the "Copy Local" flag. There are a few other modules used for .NET API support (see [The 3ds Max .NET SDK](http://help.autodesk.com/view/3DSMAX/2019/ENU/?guid=__developer_3ds_max__net_sdk_html)), but for this tutorial we will use only Autodesk.Max.dll. | ||
|
|
||
| Then search and install `Newtonsoft.Json` (which is used to parse input data in JSON format). | ||
|
|
||
| > Please select .NET Framework 4.7. If not listed, [please install the Dev Pack](https://dotnet.microsoft.com/download/dotnet-framework/net47). | ||
|
|
||
|
|
@@ -28,9 +32,61 @@ As a result, the **package.config** should look like the following for the Newto | |
|
|
||
| The project should contain a `Class1.cs` class, let's rename the file to `Command.cs` (for consistency). | ||
|
|
||
| ## PackageContents.xml | ||
|
|
||
| Create a folder named `UpdateMAXParam.bundle` and inside this folder add a file named `PackageContents.xml` that will be the AppBundle descriptor. Copy the content listed below in the XML section into the PackageContents.xml file. | ||
|
|
||
| This file will tell 3ds Max the modules to load. In this case points to the .NET API plugin assembly we will compile, but it can also include MAXScripts, Python, and/or C++ plugins. Because the dll plugin is being loaded through this feature, you only need to worry later about the instructions to trigger your automation job. Please note that a unique ID for both ProductCode and UpgradeCode are required for 3ds Max to correctly load your code. | ||
|
|
||
| > You can learn about the [PackageContents.xml Format Reference](http://help.autodesk.com/view/3DSMAX/2019/ENU/?guid=__developer_writing_plug_ins_packaging_plugins_packagexml_format_html). | ||
| > For more 3ds Max specific information for packaging your 3ds Max plugins, please see here [Packaging Plugins](http://help.autodesk.com/view/3DSMAX/2019/ENU/?guid=__developer_writing_plug_ins_packaging_plugins_html) | ||
|
|
||
|
|
||
| ```xml | ||
| <?xml version="1.0" encoding="utf-8"?> | ||
| <ApplicationPackage | ||
| SchemaVersion="1.0" | ||
| AutodeskProduct="3ds Max" | ||
| Name="Sample Design Automation Plugin for 3ds Max" | ||
| Description="A sample package to update parameters of a 3ds Max scene file containing a casement window" | ||
| AppVersion="2019.0.0" | ||
| FriendlyVersion="2019.0.0" | ||
| ProductType="Application" | ||
| SupportedLocales="Enu" | ||
| AppNameSpace="apps.autodesk.com" | ||
| Author="Autodesk Forge" | ||
| ProductCode="{6A8D06F4-C3DD-42DD-A69E-9B9617A7ABC0}" | ||
| UpgradeCode="{CE88CEA5-47F6-423E-B9EC-E9FA683B5228}" | ||
| > | ||
|
|
||
| <CompanyDetails Name="Autodesk" | ||
| Phone=" " | ||
| Url="http://forge.autodesk.com" | ||
| Email="[email protected]" /> | ||
|
|
||
| <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2019" SeriesMax="2021" /> | ||
|
|
||
| <Components Description="assemblies parts"> | ||
| <RuntimeRequirements OS="Win64" Platform="3ds Max" SeriesMin="2019" SeriesMax="2021" /> | ||
| <ComponentEntry AppName="UpdateMAXParam" Version="2019.0.0" ModuleName="./Contents/UpdateMAXParam.dll" AppDescription="The Sample Design Automation Plugin managed assembly module" /> | ||
| </Components> | ||
|
|
||
| </ApplicationPackage> | ||
| ``` | ||
|
|
||
| Create a subfolder named `Contents` and leave it empty. At this point, the project should look like: | ||
|
|
||
|  | ||
|
|
||
| ## Commands.cs | ||
|
|
||
| This is the main code that will run within 3ds Max. Copy the following content into `Command.cs`. There are three classes to handle the Design Automation processing. | ||
|
|
||
| 1. `InputParams` will interface with the JSON input data. | ||
| 2. `ParameterChanger` iterates through the scene, and find all Casement Windows models in our sample. It could also be any object types as identified by the class ids. | ||
| 3. `RuntimeExecute` takes the input and drives the automation. | ||
|
|
||
| Note there is a specialized logging that will output information to the Design Automation console. See the `LogTrace` function. Note that the `ILogSys` 3ds Max managed class is used for this, and the flags used with the `LogEntry` API indicated are necessary for the output to be shown in the Design Automation console. | ||
|
|
||
| ```csharp | ||
| using System; | ||
|
|
@@ -182,48 +238,6 @@ namespace Autodesk.Forge.Sample.DesignAutomation.Max | |
| } | ||
| ``` | ||
|
|
||
| ## Post-build event | ||
|
|
||
| > For Node.js it is required to adjust the AppBundle ZIP output folder. | ||
|
|
@@ -236,7 +250,7 @@ del /F "$(ProjectDir)..\forgesample\wwwroot\bundles\UpdateMAXParam.zip" | |
| "C:\Program Files\7-Zip\7z.exe" a -tzip "$(ProjectDir)../forgesample/wwwroot/bundles/UpdateMAXParam.zip" "$(ProjectDir)UpdateMAXParam.bundle\" -xr0!*.pdb | ||
| ``` | ||
|
|
||
| This will copy the compiled DLL from /bin/debug/ into .bundle/Contents folder. It will then use [7zip](https://www.7-zip.org/) to create a zip. And finally it will copy the ZIP into /bundles folders of the webapp. | ||
|
|
||
|  | ||
| > Note how the **Post-build event** uses the project and folder names, so make sure you're using these names. | ||
|
|
@@ -245,6 +259,8 @@ If you build the `UpdateMAXParam` project now you should see something like belo | |
|
|
||
|  | ||
|
|
||
| ## Testing locally | ||
|
|
||
| At this point, you could test the functionality using the 3ds Max batch tool. It works similarly to the 3ds Max Design Automation engine and is a good way to test all your automation locally before sending the job to the Forge DA cloud services. For .NET Classes to be instantiated in MAXScript environment, we can use the `dotNetClass` MAXScript function. For this sample project, the MAXScript code would look like this: | ||
|
|
||
| ```MAXScript | ||
|
|
@@ -257,7 +273,7 @@ fn UpdateParam = | |
| UpdateParam() | ||
| ``` | ||
|
|
||
| To execute this locally, we could do test a command-line prompt with something like this: | ||
| ```CommandLine | ||
| "%ADSK_3DSMAX_x64_2019%\3dsmaxbatch.exe" -sceneFile <myTestScene>.max da_script.ms | ||
| ``` | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
good point, maybe we should keep it consistent, upper case (AppBundle, Activity, Workitem)