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/.
1. Fusion API work off the UI thread: no
Section titled “1. Fusion API work off the UI thread: no”- 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 (runSelectCommand). 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”; atruereturn means queued, not handled.registerCustomEventreturns null on a duplicate id;unregisterCustomEventon 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.
2. Two Fusion instances on one Mac
Section titled “2. Two Fusion instances on one Mac”open -n“Open a new instance of the application(s) even if one is already running.”man open(macOS 26, local). Apple documents nothing about Fusion specifically.- Autodesk licensing FAQ [excerpt]: a single-user subscription “can be installed … on up to three devices, but can only have one active session running at a time”; “More than one active, concurrent session running on different devices is not compliant and is considered a violation of our Terms of use”. It says nothing about two sessions on one device. https://www.autodesk.com/support/account/admin/licensing-faq/authorization (403 to fetch; wording from search excerpt)
- [forum] Autodesk staff on two instances on one machine: a QA engineer “would not recommend it”; community manager Jeff Strater would not run it “mostly because of compute/memory resources” and warns against editing the same model twice; users report one or both instances freeze/crash more. https://forums.autodesk.com/t5/fusion-design-validate-document/multiple-instances-of-fusion-360-on-windows/m-p/12337881 , https://forums.autodesk.com/t5/fusion-design-validate-document/can-you-have-more-than-1-instance-of-fusion-360-running-on/m-p/6294468
- [forum] Fusion “detects when multiple sessions are running and asks the user to end the others” (community member, not Autodesk). https://forums.autodesk.com/t5/installation-licensing-forum/maximum-number-of-computers-for-single-user-subscription/m-p/9587513
- Practical reading: a second instance under a second macOS user with a second Autodesk account (its own trial/personal licence) is the only configuration that does not collide with the one-session rule, and it is unsupported by Autodesk. Also the MCP server binds a fixed local port (
http://127.0.0.1:27182, may move after restart; see shared notes), so the second instance would need its own port. Cost: a second account + both instances competing for the same CPU/GPU, which is what makes the first one beachball.
3. Headless / cloud
Section titled “3. Headless / cloud”- 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.pyfrom Python to TypeScript against the automation subset (unknown whether the previewmeshConvertFeaturesis 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.
4. Convert once, insert many
Section titled “4. Convert once, insert many”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.isCompletetells 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”) andaddNewComponentCopy(“Paste New”) reuse a component already in the document;createFusionArchiveImportOptions(filename)imports an f3d from disk (“only supports f3d files”; f3z needsDataFolder.uploadFile), andimportToTarget2returns 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
addByInsertthe 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 needcreateForAssemblyContext(occ)orisReferencedComponent=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 noMeshImportOptionsobject 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) withMeshReduceFeatureInput.meshReduceTargetType(MaximumDeviation default, Proportion, FaceCount),maximumDeviation,proportion,facecount,meshReduceMethodType(Adaptive default),targetBaseFeature. REF/fusion_MeshReduceFeatures.htm , REF/fusion_MeshReduceFeatureInput.htm - Convert settings:
meshConvertMethodTypeFaceted (default) / Prismatic / Organic;meshConvertResolutionType(ByAccuracy default, ByFacetNumber) andmeshConvertAccuracyType(Medium default) are “Valid only when meshConvertMethodType is Organic”;numberOfFacesonly 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:
BaseFeatureis “a direct edit feature within a parametric design”;Design.designType = DirectDesignTyperemoves “the timeline and all design history”;Timeline.markerPositioncan 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:
- OCCT via
cadquery-ocp(pip wheels for CPython 3.11–3.14, macOS 11+ arm64 and x86-64; latest 8.0.1.1.0, Oct 2026).STEPControl_Readerreads STEP;RWStl.ReadFile“Read specified STL file and returns its content as triangulation” (Poly_Triangulation, not a solid).BRepExtrema_DistShapeShape“compute minimum distance between two Shapes”,SetMultiThread(true)runs “in parallel”,Value()is the minimum.BRepExtrema_ShapeProximitydetects faces within a tolerance from existing triangulation (“poly triangulation … should already be built”), result “approximate” to the deflection. https://pypi.org/project/cadquery-ocp/ , https://occt3d.com/dev/doc/refman/html/class_r_w_stl.html , https://occt3d.com/dev/doc/refman/html/class_b_rep_extrema___dist_shape_shape.html , https://occt3d.com/dev/doc/refman/html/class_b_rep_extrema___shape_proximity.html - CadQuery / build123d are thin layers on the same OCP:
Shape.distanceisBRepExtrema_DistShapeShape(...).SetMultiThread(True).Value(),distances()reuses one solver withLoadS1/LoadS2. CadQuery:pip install cadquery, Python 3.9+, macOS supported; build123d:pip install build123d. https://github.com/CadQuery/cadquery/blob/master/cadquery/occ_impl/shapes.py , https://cadquery.readthedocs.io/en/latest/installation.html , https://build123d.readthedocs.io/en/latest/installation.html - FreeCAD 1.1.4 (
brew install --cask freecad, arm64 and x86_64; the cask installs only/Applications/FreeCAD.app, nofreecadcmdsymlink, so call the binary inside the bundle).Part.read(filename)“Load the file and return the shape” (.stp/.step,.igs,.brepby extension);Shape.distToShape(shape, tol) -> (dist, vectors, infos)wrapsBRepExtrema_DistShapeShapewithSetMultiThread(true)on OCC >= 7.6;Part.makeShapeFromMesh((vertex,facets), tol)“should be used for rather small meshes only”;Mesh.readloads STL. Same engine, same cost as OCP, plus a 1 GB app. https://formulae.brew.sh/api/cask/freecad.json , https://github.com/FreeCAD/FreeCAD/blob/main/src/Mod/Part/App/AppPartPy.cpp , https://github.com/FreeCAD/FreeCAD/blob/main/src/Mod/Part/App/TopoShapePyImp.cpp , https://github.com/FreeCAD/FreeCAD/blob/releases/FreeCAD-1-0/src/Mod/Part/App/TopoShapePy.xml , https://github.com/FreeCAD/FreeCAD/blob/main/src/Mod/Mesh/App/AppMeshPy.cpp - trimesh (
pip install trimesh rtree scipy):proximity.closest_point(mesh, points)“find the closest point on any triangle” using “an r-tree containing the axis aligned bounding box for every triangle”;nearby_facesguarantees the closest point is on a listed face. Mesh-to-mesh minimum distance is not a built-in; vertex-to-surface both ways is an upper bound (exact when the closest pair includes a vertex). https://github.com/mikedh/trimesh/blob/main/trimesh/proximity.py
[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.progressBargives a progress bar “in the lower-right corner of the Fusion window”; withdoEventsit at least shows the build is alive. REF/core_UserInterface_progressBar.htmViewport.refresh“Forces the view to redraw”;Viewport.visualStyleis settable (wireframe is cheaper to draw during a build);ImportOptions.isViewFit = Falseavoids camera churn per import. REF/core_Viewport.htm , 2026-10-31-model.md §1Application.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.htmDocuments.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.htmDesign.designTypedirect, or building inside oneBaseFeature, avoids timeline recompute while bodies are added (§4).
Recommendations
Section titled “Recommendations”- (1 h) Decimate proxies to edge length < threshold and screen with KD-tree outside Fusion.
scipy.cKDTree0.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 inmodel/build/proxies). Gain: sweeps off Fusion, UI free during sweeps. - (2 h) Chunk the build through custom events. Worker thread +
fireCustomEventper 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 h) Build a parts library once, insert per Stage. One document per printed part (import, reduce, convert, proxy),
saveAsinto project “Noggin”, thenaddByInsert(same project) in Stage builds, oraddExistingComponentfrom a library document opened withvisible=False. Gain: Stage builds skip 15 mesh->BRep converts (the dominant cost); risk: x-ref joint geometry needscreateForAssemblyContext, andisCompletemust be true before insert. - (2 h, experiment) Reduce before convert, try Prismatic.
MeshReduceFeatureswithmaximumDeviationthenmeshConvertFeatures; test Prismatic and OrganicByFacetNumberon one 75k part. Gain: fewer BRep faces makes convert, measure and display cheaper; unknown whether the organic eye shapes survive. - (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.
- (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.
noggin v0.2.26-6-g09bf9b7 · 09bf9b7