pyNavis Tool authoring guide
/
pynavis 1.0.0

pyNavis authoring guide

Build tools for Navisworks

Everything you need to turn a folder and a Python file into a button on the Navisworks ribbon. No compiler, no Visual Studio, no restart.

New here

Read Your first button first. It gets a working tool on the ribbon in about five minutes, and every other page assumes you have done it.

pyNavis loads extensions from disk at startup. An extension is a folder tree whose folder names describe the ribbon: a .tab becomes a ribbon tab, a .panel becomes a panel on it, and a .pushbutton becomes a button that runs the script.py inside it. There is no manifest to register, no project to compile, and no build step. Create the folders, drop in a script, press Reload.

These pages document the authoring surface exhaustively: every folder suffix the runtime recognises, every key it reads out of bundle.yaml, every global it injects into your script, and every function in the pynavis library. Where the runtime has a sharp edge, it is called out rather than glossed over.

Start

How pyNavis worksThe mental model behind every tool you will write: folders on disk become buttons on the ribbon, and a button runs a Python file. Your first buttonBuild a working Navisworks tool from an empty folder in about five minutes, then extend it with an icon, a tooltip, a keyboard shortcut and a settings dialog. Bundled toolsEvery tool that ships on the pyNavis ribbon tab, panel by panel: what it does, what it needs, what happens on click, and what its settings change.

Bundles

Anatomy of an extensionThe four folder levels, how discovery walks them, and the ordering and naming rules that decide what your ribbon looks like. Buttons, stacks and pulldownsThe three things a panel holds most often, what each one costs you in space, and nine narrower kinds for when a plain button is not quite the shape you need. The bundle.yaml referenceEvery key the runtime reads, what it falls back to, and the exact rules of the very small parser that reads the file. IconsFour PNGs per bundle, why they are the sizes they are, and the drawing language behind the shipped set. Shortcuts and keytipsKeyboard chords that run a tool without touching the ribbon, and the Alt letters that walk to it. Click actions and config.pyOne button, three behaviours: a plain click runs the script, Shift runs the bundle's config.py, and Alt opens the folder it lives in. HooksScripts that run themselves, triggered by something happening in Navisworks rather than by a click.

Scripts

The script environmentWhat the runtime does between the click and the first line of your code, and every rule that follows from it. Talking to the userFour surfaces carry everything a tool says: a toast, a modal dialog, the HTML output window, and a custom window. Picking the right one is most of the work. Settings and per-tool stateHow a tool remembers what the user chose, using one small module and one JSON file per tool.

Reference

Python API referenceEvery public function in the pynavis library, with its exact signature, return value and failure behaviour.

Practice

CookbookComplete, runnable recipes for the jobs a Navisworks tool actually has to do, with the sharp edge on each one named. TroubleshootingEvery way a bundle fails, listed by what you actually see, with the cause, the fix, and the log line that proves it. Design rules for toolsA shared look and a shared set of manners, so that twenty tools written by ten people still feel like one product.