Skip to content
noggin

Fusion throughput research (2026-10-31)

Question: a Stage build (~15 STLs of 10k–75k faces converted with meshConvertFeatures, plus a 600-body STEP) takes 2–3 minutes with the Fusion UI beachballing, and sweeps measure proxies with measureMinimumDistance. Can the UI stay usable, or can the work leave Fusion?

Base URL for API reference links: https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/ (abbreviated REF/). Forum/search-excerpt claims are marked [forum] / [excerpt] (Autodesk forum and account pages return 403 to fetch tools). Numbers marked [measured] come from scripts run today on this Mac (uv run --python 3.12, Apple Silicon), scripts in the session scratchpad bench/.

  • Scripts and add-ins (Python and TypeScript) run “within the Fusion process on the main Fusion thread”; while one runs “most of Fusion appears frozen because it never gets a chance to react to messages”. REF/TypeScriptSpecific_UM.htm
  • adsk.doEvents() “temporarily halts the execution of the add-in or script” and “gives Fusion a chance to handle any queued up messages” (Python); C++: “pauses execution of your script or add-in and allows Fusion to process all messages currently in its queue”, for when a program “drives Fusion faster than Fusion can refresh its graphics”. It is a yield for repaint/input, not a way to run work concurrently. REF/PythonSpecific_UM.htm , REF/CPPSpecific_UM.htm
  • Threads: “Your worker thread should never do any work inside Fusion because that should always be done in the main thread”; calling API functions from a worker “can crash Fusion”, “even messageBox”. The worker’s only job is app.fireCustomEvent(eventId, json); Fusion then runs the handler on the main thread. Before edits that add undo steps the handler must terminate any active command (run SelectCommand). REF/Threading_UM.htm , REF/CustomEventSample_Sample.htm
  • fireCustomEvent: the event “is put on the queue and will be handled in the main thread when Fusion is idle”; a true return means queued, not handled. registerCustomEvent returns null on a duplicate id; unregisterCustomEvent on cleanup. REF/core_Application_fireCustomEvent.htm , REF/core_Application_registerCustomEvent.htm , REF/core_Application_unregisterCustomEvent.htm
  • [forum] Autodesk’s Brian Ekins: the API “runs in the single main thread and can’t be called from another thread”; doEvents “won’t have any effect on how Fusion computes the model”. https://forums.autodesk.com/t5/fusion-api-and-scripts-forum/related-items-aren-t-updated-after-sketch-is-changed-adsk/td-p/9161034
  • No async/queued execution exists: Documents.add(visible=False) is documented as “documents can only be created visibly so this argument must always be true”; Documents.open(dataFile, visible=False) does exist (“Specifies if the document should be opened visibly or not”). REF/core_Documents_add.htm , REF/core_Documents_open.htm
  • What is allowed off the main thread: anything that does not touch adsk.* (file IO, HTTP, math, waiting on the MCP socket). The useful pattern is therefore: worker thread holds the job queue and fires one custom event per small step; each handler does one STL import/convert, returns, and Fusion repaints and takes input between steps. The UI is usable between steps, not during a 75k-face convert.
  • Fusion Automation API (APS): GA 19 May 2025, “a Premium API with a cost of 3.0 Flex tokens per processing hour”; “Every second counts towards your processing hours, including the time it takes to transfer files between systems.” Scripts are TypeScript, run “in a secure sandbox environment, both locally during development and in the cloud”, “without requiring any user interaction”, against “data you already store on Fusion Team”; parallel jobs allowed. https://aps.autodesk.com/blog/design-automation-api-fusion-now-generally-available , https://aps.autodesk.com/blog/design-automation-fusion-open-beta
  • Requirements: an APS application (client id/secret) plus a Personal Access Token for remote runs; the VS Code extension runs TypeScript scripts locally inside Fusion or remotely; activities + work items (Design Automation v3 style). https://aps.autodesk.com/blog/get-started-automation-api-fusion
  • Service scripts import @adsk/fusion/automation, “only the subset of the API that is available in the service environment”; desktop-only calls fail at runtime. File system access “is sandboxed to a special temporary directory”. REF/TypeScriptSpecific_UM.htm
  • No desktop headless mode is documented anywhere in the API reference; the reference pages for doEvents, threading and TypeScript all assume the GUI process. The 2026 what’s-new posts (April: Autodesk Assistant writes/runs API scripts; July: “new capabilities across … API development”) return 403 to fetch; only search excerpts seen. https://www.autodesk.com/products/fusion-360/blog/july-2026-major-product-update-whats-new/
  • What it would cost here: porting fusion_lib/check.py from Python to TypeScript against the automation subset (unknown whether the preview meshConvertFeatures is in it; not documented), Flex tokens (3/h, buy in packs), and each run uploads 600-body STEP + STLs via Fusion Team. Not a 30-day-trial fit.
  • occurrences.addByInsert(dataFile, transform, isReferencedComponent) “Method that inserts an existing file”; fails “if the dataFile being inserted is not from the same project … while isReferencedComponent is True”. Document.dataFile “Gets the DataFile that represents this document in A360”; DataFile.isComplete tells whether cloud processing has finished (a just-saved part may not be insertable yet). REF/fusion_Occurrences_addByInsert.htm , REF/core_Document_dataFile.htm , REF/core_DataFile.htm
  • First save of a new document needs saveAs(name, dataFolder, description, tag); “Saving a document is not supported within any of the Command related events”. REF/core_Document_saveAs.htm , REF/core_Document_isSaved.htm
  • Alternatives that avoid the cloud round trip: occurrences.addExistingComponent(component, transform) (“copying and pasting an occurrence”) and addNewComponentCopy (“Paste New”) reuse a component already in the document; createFusionArchiveImportOptions(filename) imports an f3d from disk (“only supports f3d files”; f3z needs DataFolder.uploadFile), and importToTarget2 returns the created objects. REF/fusion_Occurrences_addExistingComponent.htm , REF/fusion_Occurrences_addNewComponentCopy.htm , REF/core_ImportManager_createFusionArchiveImportOptions.htm , REF/core_ImportManager_importToTarget2.htm
  • So the supported path is: one “parts library” build that imports+converts each STL and the STEP once, saves (a Fusion design per part, or one library design), then Stage builds addByInsert the saved DataFiles (same project, referenced or embedded) or import the exported f3d. Expected cost: a referenced insert loads a stored BRep (no mesh->BRep compute); the reference does not publish timings. Caveats already known for this repo: joints to x-ref geometry need createForAssemblyContext(occ) or isReferencedComponent=False (see 2026-10-31-model.md §6); the proxy bodies would have to live in the saved part.
  • Mesh import: meshBodies.add(fullFilename, units: MeshUnits, baseOrFormFeature=None); “In a parametric design, a new mesh base feature is created automatically”; STL “always contain a single body”; units are only for unitless STL/OBJ. MeshUnits: cm=0, mm=1, m=2, in=3, ft=4. There is no MeshImportOptions object in the reference (the ImportManager page does not exist, 404). REF/fusion_MeshBodies_add.htm , REF/fusion_MeshUnits.htm
  • Reduce before convert: MeshReduceFeatures (preview, March 2024) with MeshReduceFeatureInput.meshReduceTargetType (MaximumDeviation default, Proportion, FaceCount), maximumDeviation, proportion, facecount, meshReduceMethodType (Adaptive default), targetBaseFeature. REF/fusion_MeshReduceFeatures.htm , REF/fusion_MeshReduceFeatureInput.htm
  • Convert settings: meshConvertMethodType Faceted (default) / Prismatic / Organic; meshConvertResolutionType (ByAccuracy default, ByFacetNumber) and meshConvertAccuracyType (Medium default) are “Valid only when meshConvertMethodType is Organic”; numberOfFaces only with ByFacetNumber. Organic needs the Product Design Extension (included in the full trial). So the paid tier does not make faceted cheaper; it adds Organic, which can target a small face count (numberOfFaces) instead of one face per triangle. Prismatic (merged planar/cylindrical face groups) is the cheapest BRep for mechanical STLs and needs no extension; its success on these organic eye parts is untested. REF/fusion_MeshConvertFeatureInput.htm , REF/fusion_MeshConvertResolutionTypes.htm , REF/fusion_MeshConvertMethodTypes.htm
  • Direct vs parametric: BaseFeature is “a direct edit feature within a parametric design”; Design.designType = DirectDesignType removes “the timeline and all design history”; Timeline.markerPosition can roll the timeline back. Converting inside a base feature or in a direct design avoids timeline recompute on every later edit. REF/fusion_BaseFeature.htm , REF/fusion_Design_designType.htm , REF/fusion_Timeline_markerPosition.htm

5. Geometry checks outside Fusion (macOS, headless)

Section titled “5. Geometry checks outside Fusion (macOS, headless)”

All three stacks read STEP and STL on macOS with pip/brew and run without a GUI:

[measured] on L eyeball regular.stl (36,280 tris) vs main bracket.stl (9,400) and the servo STEP, in their raw STL coordinates (so the distance values are meaningless, only the times matter):

method time
OCCT: one planar BRep face per triangle (what Faceted convert is), build 36k + 9k faces 0.87 s + 0.22 s
OCCT BRepExtrema_DistShapeShape 36k-face vs 9k-face, single thread 88 s
same, SetMultiThread(True) 17 s
OCCT STEP servo solid (real surfaces) vs 9k-face BRep 2.2 s
trimesh closest_point all 36k vertices onto 9k-tri mesh, both ways 6–15 s
trimesh closest_point on every 20th vertex 0.19 s
scipy cKDTree vertex-to-vertex 36k -> 9k 0.02 s

Reading: OCCT exact distance on faceted BReps is slower than Fusion’s measureMinimumDistance on proxies (~0.1 s/pair, shared notes), so moving exact checks out of Fusion does not pay. A KD-tree vertex-vertex sweep is 1000x faster and is a correct upper bound; with proxies decimated so the longest edge is below the clearance threshold (today’s max edge is 24.8 mm, far too long), vertex-vertex alone becomes a sufficient screen, and only screened pairs need an exact check.

6. Other things that keep the UI responsive

Section titled “6. Other things that keep the UI responsive”
  • UserInterface.progressBar gives a progress bar “in the lower-right corner of the Fusion window”; with doEvents it at least shows the build is alive. REF/core_UserInterface_progressBar.htm
  • Viewport.refresh “Forces the view to redraw”; Viewport.visualStyle is settable (wireframe is cheaper to draw during a build); ImportOptions.isViewFit = False avoids camera churn per import. REF/core_Viewport.htm , 2026-10-31-model.md §1
  • Application.executeTextCommand(command) “Executes the input text command” (May 2020) is the only documented hook into Fusion’s internal commands; nothing documented turns graphics off. REF/core_Application_executeTextCommand.htm
  • Documents.open(dataFile, visible=False) opens saved designs without a viewport (not creatable invisibly, see §1), useful for a parts library that is read, not shown. REF/core_Documents_open.htm
  • Design.designType direct, or building inside one BaseFeature, avoids timeline recompute while bodies are added (§4).
  1. (1 h) Decimate proxies to edge length < threshold and screen with KD-tree outside Fusion. scipy.cKDTree 0.02 s per pair vs 0.1 s in Fusion, and the sweep leaves the UI alone entirely; Fusion only confirms screened pairs. Needs the proxies exported once as STL (already in model/build/proxies). Gain: sweeps off Fusion, UI free during sweeps.
  2. (2 h) Chunk the build through custom events. Worker thread + fireCustomEvent per part, handler does one import+convert and returns; progressBar + doEvents. Gain: Fusion repaints and takes clicks between parts; total build time unchanged or slightly longer.
  3. (3 h) Build a parts library once, insert per Stage. One document per printed part (import, reduce, convert, proxy), saveAs into project “Noggin”, then addByInsert (same project) in Stage builds, or addExistingComponent from a library document opened with visible=False. Gain: Stage builds skip 15 mesh->BRep converts (the dominant cost); risk: x-ref joint geometry needs createForAssemblyContext, and isComplete must be true before insert.
  4. (2 h, experiment) Reduce before convert, try Prismatic. MeshReduceFeatures with maximumDeviation then meshConvertFeatures; test Prismatic and Organic ByFacetNumber on one 75k part. Gain: fewer BRep faces makes convert, measure and display cheaper; unknown whether the organic eye shapes survive.
  5. (4 h+, not recommended) Second Fusion instance under a second macOS user and Autodesk account. Unsupported by Autodesk, one-session rule per account, two instances share the CPU that is already saturated, second MCP port.
  6. (days, not recommended) Fusion Automation API. TypeScript port, APS app + PAT, Fusion Team uploads, 3 Flex tokens/h, preview mesh-convert availability unknown in the service subset.
byYellow PineYellow Pine

noggin v0.2.26-6-g09bf9b7 · 09bf9b7