Start

Bundled tools

Every 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.

pyNavis installs one extension of its own, pyNavis.extension, which builds the pyNavis tab. This page is the user manual for what is on that tab. It is also worth reading as a set of worked examples: every tool here is an ordinary bundle, written the way Your first button describes, and its source sits in the extension folder next to yours.

Panels appear in folder-name order, so the tab reads General, Memory, Tools, Viewpoints, and buttons inside a panel follow the same rule with the leading NN_ stripped from the label. Three of the four panels end in a flyout: the panel title carries a small arrow, and clicking it opens the rest, exactly like the native Tags panel. Those tools are listed here under In the flyout.

How to read the entries#

• Needs is the bundle's context: expression. When it is not satisfied the button is greyed out and cannot be clicked. Tools with no condition are always clickable and report with a toast instead.
• Shift+Click runs the bundle's config.py, which is where a tool keeps its options. Tools without one answer Shift+Click with an informational toast saying the action is not defined.
• Alt+Click works on every tool here and is not repeated below: it opens the bundle folder in Explorer with script.py selected.
• Settings names the file a tool reads. Per-tool settings live in %APPDATA%\pyNavis\settings\, one JSON file per tool; anything described as living in config.json is in %APPDATA%\pyNavis\config.json.
• Keyboard shortcuts are the shipped defaults. Every one of them can be rebound or switched off in the shortcuts editor, and a chord always runs the primary script, never the Shift+Click action. See Keyboard shortcuts.

General panel#

Console#

An interactive Python console running inside Navisworks, in the same process and with the same environment your scripts get. It is the fastest way to try an API call before writing it into a bundle.

• Click opens the console window. Type in the lower pane and run with Ctrl+Enter; the Run button does the same. Up and Down at the edges of the input walk back through what you have already run, and output collects in the upper pane.
• Needs nothing. It opens with no document.

Reload#

Rescans every extension folder and rebuilds the ribbon without restarting Navisworks. This is the second half of the development loop: edit a file, click Reload, click your button.

• Click rebuilds the tab and toasts when it is done. It picks up new and renamed bundles, changed bundle.yaml values, new icons and changed shortcuts, and it reruns each extension's startup.py.
• Needs nothing.

Settings#

A window over the parts of config.json you are meant to change. Four groups:

• Appearance: the theme, which can follow Navisworks or be forced light or dark; whether a small dot marks tools that have a Shift+Click action; and the marker drawn on tools that have a shortcut, which an empty box switches off. The tooltip still names the keys either way.
• Shortcuts: whether a binding may leave out both Ctrl and Alt. Off, a chord must contain one of them. Which tool holds which chord is not edited here, it belongs to the shortcuts editor.
• Where extensions are loaded from: add and remove the folders pyNavis scans for *.extension folders. Two defaults are scanned whether or not they are listed here: %APPDATA%\pyNavis\extensions, where the install puts the shipped extension, and %PROGRAMDATA%\pyNavis\extensions when it exists.
• Engines: the pynavislib folder and the CPython executable. Leave either empty to let pyNavis resolve it; CPython is only needed by bundles that declare engine: cpython.

• Click opens the window. Cancel says nothing. Saving writes config.json and then does one of two things: if an engine path changed it warns that Navisworks needs restarting, because a Reload cannot pick those up; otherwise it offers to reload pyNavis there and then, and tells you either way whether the change is showing yet.
• Needs nothing.

Shortcuts#

The keyboard shortcut editor: every bundle that can carry a chord, with the chord it has now, searchable.

• Click opens the editor. Click a field and press the keys you want; Backspace clears a binding so the tool has none, Esc leaves a field as it was. Each row can be reset to the bundle's own default, and one action restores every default at once. Saving writes your overrides into config.json under shortcuts.bindings, reloads pyNavis so the new chords are live, and toasts.
• Needs nothing.

In the flyout: Panel slots#

A *.dockpane bundle needs a slot in the loader to live in, and five slots ship with pyNavis. Each dock pane bundle claims one for life, recorded in config.json under panes.assignments. This tool makes more slots when five is not enough.

• Click reports how many slots exist now and asks how many extra you want, up to 95. It then generates a satellite assembly holding them and reports the new total. The new slots exist only after Navisworks is restarted.
• Needs nothing, and no administrator rights. The satellite is written beside the loader in %APPDATA%\Autodesk\ApplicationPlugins\pyNavis.bundle\Contents\<year> and registered in the bundle's PackageContents.xml.

Memory panel#

The memory is one register of model items per document, the way a calculator has one memory. You put a selection in it, keep working, and take it back out later. It is stored as a file under %APPDATA%\pyNavis\memory\, so it outlives closing the document and closing Navisworks, and it is keyed to the document rather than to the session: reopen the model tomorrow and the memory is still there. Nothing is written into the model itself, so the document is never marked modified by it.

The usual run of it: MWrite to store what you have selected, MAppend and MDeduct and Intersect to grow, shrink or narrow it as you find more, MRead to select the whole thing again, Prev and Next to walk the items one at a time, and Save as Set when the set is worth keeping in the document. None of these buttons declares a context condition, so none of them greys out; an empty memory or an empty selection is reported in a toast.

MWrite#

Replaces the memory with the current selection. The starting point for everything else on this panel.

• Click stores the selection and toasts how many items went in. With nothing selected it says so and changes nothing.
• Shortcut Ctrl+Shift+M.

MRead#

Selects whatever is in the memory, replacing the current selection.

• Click resolves every stored item back to the model and selects it. Items that are no longer there, because the model was reloaded or the item was deleted, are counted in the toast and skipped rather than failing the whole recall.
• Shortcut Ctrl+Shift+R.

MAppend#

Adds the current selection to the memory, keeping what was already there. Use it to build up a set over several passes through a model.

MDeduct#

Removes the current selection from the memory. The way to carve out the part of a stored set you have decided is not wanted.

Intersect#

Keeps only the items that are in the memory and selected right now. Two searches in a row, one stored and one live, reduced to what they agree on.

Prev and Next#

Selects a single item from the memory and zooms to it, then the one after it, then the one after that. This is how you walk a list of items you found earlier, one at a time, without losing your place.

• Click moves the cursor one step and selects and zooms to that item. Both wrap around, so Next at the end of the list returns to the start. The camera move cannot be undone.
• Shortcut Ctrl+Shift+Left for Prev, Ctrl+Shift+Right for Next, which is the point of the pair: you walk the list from the keyboard while looking at the model.

MClear#

Empties the memory for this document, and reports how many items were dropped. Other documents keep theirs.

Memory menu#

The pulldown at the end of the panel holds the three things you do to the memory rather than with it.

• Show Contents lists what is in the memory in the output window, one row per item with the model it came from and a link that selects it, under a line naming the document it was memorized from and when. Long memories are cut off at 500 rows. An empty memory prints a line telling you to select something and press MWrite.
• Save as Set promotes the memory to a native Navisworks selection set. It asks for a name, offering "Memory" plus the date and time, and creates the set. Unlike the memory, a selection set is stored inside the document, so this marks the document modified and the set travels with the file.
• Purge deletes the stored memory files for every document, not just this one. It counts the files first and asks for confirmation naming that number, and says so quietly when there is nothing to delete.

Tools panel#

Clash Report#

A one-screen summary of every test in Clash Detective, for the moment you want the numbers rather than the results. Useful in a coordination meeting, or as the evidence line in a report.

• Click prints a table in the output window, one row per test, with the total and the count in each status: New, Active, Reviewed, Approved and Resolved. A line underneath totals the tests and the results. It then asks whether to export the same table to CSV and, if you say yes, where to save it. A document with no clash tests gets a dialog saying so instead.
• Needs no condition, so the button is always live.

Get Coordinates#

Click a point in the view and its coordinates land on the clipboard, ready to paste into Go to Coordinates, into a report, or back into the authoring model.

• Needs an open document.
• Click puts the view into a pick that runs on the native Measure tool, so the pointer snaps to vertices, edges and line ends exactly as a measurement does, and the point that reaches the clipboard is the snapped one rather than wherever the cursor was. The text is written as "X, Y, Z" at three decimals in model units, which is the shape Go to Coordinates reads back. Esc, a right-click or picking another tool cancels and copies nothing, with no complaint.

Go to Coordinates#

Moves the view to a set of coordinates and marks the point with a cross. The other half of the pair: a point copied by Get Coordinates, or pasted out of a clash report or a survey schedule, is one click from being on screen.

• Needs an open document.
• Click opens a box already filled with the clipboard's coordinates when the clipboard holds three numbers, and empty when it holds anything else. The camera then keeps the direction it is already looking and only moves, standing five metres back from the point in the model's own units, so the angle you set up survives and the point lands in the middle of the view. The focal distance moves with it, so orbiting straight afterwards turns around the point rather than around where the camera used to pivot. A cross labelled with the coordinates is drawn on the point.
• Shift+Click clears the marker and leaves the view alone.

Select by IDs#

Selects elements by Revit element ID, in a federated model, without opening Revit. Paste a column of IDs out of a clash report, a schedule or an email and the elements are selected in the view.

• Needs an open document.
• Click opens a paste box, already filled with the clipboard's IDs when the clipboard holds something that looks like IDs, and always shows them for approval and editing before anything is searched. The search then looks in both places an element ID survives federation: the "Element ID" property tab an NWC exported from Revit carries, and the "[123456]" suffix a model published straight through design coordination carries in its name instead. Whichever shape works moves to the front for the remaining IDs. Above one ID, a progress window with a cancel button names the ID being looked for. What is found replaces the current selection, and is zoomed to or isolated according to the settings.
• Shift+Click opens the element ID settings below.

IDs of Selection#

The reverse trip: copies the Revit element IDs of whatever is selected to the clipboard, ready to paste into Select by IDs, into Revit's own Select by ID, or into a report.

• Needs a selection.
• Click resolves an ID for each selected item, reading it off the nearest ancestor that is a real element, because a click in the view usually lands on a geometry leaf below the element. The list goes to the clipboard. The toast names a single ID rather than counting it, and always reports how many selected items carry no ID at all, so the tool never finishes looking as though it did nothing.
• Shift+Click opens the element ID settings below.

Export Viewpoints#

Writes every saved viewpoint in the document to a CSV file: name, folder path, type and camera position. For an audit of what a model's saved views actually are, or to diff two issues of the same model.

• Click asks where to save, offering the document's title plus _viewpoints.csv, and writes one row per saved item with the columns Name, Folder, Type, CameraX, CameraY and CameraZ. The saved-viewpoints tree also holds animations and cuts, which have no camera of their own, so those rows are written with the three position columns blank rather than being dropped. A document with no saved viewpoints gets a dialog saying so.

Face Distance#

The true perpendicular distance between the two faces a point-to-point measurement touches. A rotated project makes the measure tool's X, Y and Z readouts meaningless, and the straight line overshoots whenever the two clicks are not exactly opposite each other. This reports the gap, not the line.

• Needs an open document.
• Click opens the native Measure, Point to Point tool and asks for the two faces, one toast per click. Esc, a right-click or choosing another tool cancels quietly. Once the line is measured it works out which faces each point sits on from the items' own triangles rather than from a screen pick, picks the pair of faces that are parallel, and toasts the measured vector projected onto their normal. The same value is drawn in the view as a dimension square to the faces, beside the native measurement, which stays on screen with its own readout; the document is left on the Measure tool so the next two clicks measure again, and the dimension goes when that measurement changes.
• Shift+Click asks two numbers: the fraction a feet-and-inches reading is rounded to, which starts at 1/128 to match the native measure readout, and how far two faces' normals may differ and still count as parallel, which starts at one degree.
• Settings face_distance.json.

Resolve Clash#

Objects clash, and the usual next step is to drag one of them with Item Tools until it clears, read the offset, and type it into the authoring tool. This does the dragging. Pick the object that should move, pick what it must clear, and it slides the shortest axis-aligned distance that ends every contact, then tells you how far.

• Needs an open document. The two objects are read from their own triangles, so any shape works, not just boxes, and a fitting that clips the corner of a rotated wall is solved on the faces that actually meet.
• Click twice. With the object that should move selected, click: it is remembered and the toast asks for the obstacle. With the obstacle selected, click again. The move is worked out exactly for each of the six axis directions (or both ways along the one axis chosen in the options), the shortest is applied as the same permanent transform Item Tools makes, the moved object is selected, and the toast reads "Moved Pipe 1234 up by 152 mm". Ctrl+Z puts it back. Clicking with nothing selected, or opening another file between the two clicks, starts over.
• Already clear objects are reported with their gap along the nearest axis and left alone. Touching counts as contact, the way a hard clash at zero tolerance does, so a touching pair with no clearance set is "already clear" and one with a clearance is pushed apart by exactly that much.
• Shift+Click asks a direction, Auto or X, Y or Z only, and a clearance in the document's units. Clearance is measured along the axis moved: the object ends up that far from the obstacle in the direction it travelled. The setting is stored with its unit, so 25 mm stays 25 mm in a feet-and-inches document.
• Limits Objects with tens of thousands of triangles each can take a while; after 30 seconds it gives up with "Too detailed to solve". One object entirely inside another shares no surface with it and reads as clear, as it does in Clash Detective.
• Settings resolve_clash.json.

Sets from Excel#

Round-trips selection sets through an Excel workbook. Export to review a model's sets in a spreadsheet or hand them to someone, edit the rows, and import them back as new sets, or carry a library of standard sets from one federated model to the next.

• Needs an open document.
• Click asks whether you are exporting or importing. Export asks where to save an .xlsx and writes one row per search condition, with the columns Folder, Set, Category, Property, Op and Value; a set with several conditions repeats its folder and name once per condition. A set that carries no conditions, including an explicit static set, still gets a row with the condition columns blank so that it stays visible in the workbook, and those rows are skipped again on the way back in. Import asks for a workbook, checks every row before touching the document, prints the problems to the output window and refuses if there are any, and otherwise creates the sets behind a progress window you can cancel.

Smart Clash Grouper#

Turns a clash test's results into reviewable issues. Three hundred clashes between the same two runs of pipework are one problem, and this is the tool that says so before anyone opens a report.

• Click opens a dialog listing the tests in the document with their result counts, filled in as it counts them. Pick tests, then either leave smart grouping on, which groups by the root-cause element, or chain your own rules: element on side A or side B, proximity cluster, nearest level, grid intersection, source model, status, or assigned to. A live preview shows the groups the current rules would produce before anything is written, and there is an ungroup action that removes only the groups this tool made and never touches hand-made ones. Writing reports each test in the output window: the grouping explanation, the largest groups with a link that shows the first clash in each, how many clashes were left in existing groups and how many were left individual.
• Shift+Click presets what the dialog opens with: smart mode on or off, the custom rule chain, the proximity cluster distance, which starts at two metres, and whether existing groups are kept. Every run can still change all of it in the dialog itself.
• Settings smart_clash_grouper.json.

In the flyout: Element ID Settings#

The settings shared by Select by IDs and IDs of Selection, in the panel flyout so they can be found without knowing about Shift+Click. It is the same window either button opens on Shift+Click, and there is one store behind it, because which property holds the ID is a fact about the model rather than about the button that reads it.

• Property category and property, which start at "Element ID" and "Value", the tab and field the Revit exporter writes. A blank box falls back to the default rather than saving an empty value that would make every search fail with no visible cause.
• Zoom onto what was selected, on by default.
• Isolate, which hides everything else as well, off by default.
• Fill the box from the clipboard, on by default.
• Select every copy, off by default. Off, one ID resolves to one item and the search stops at the first hit, which is around eight tenths of a second per ID. On, it keeps walking for every copy of the element, which is a full walk of the document per ID, around three seconds. The case for turning it on is the same element exported into two sibling files.

Viewpoints panel#

Renamer#

Batch renames saved viewpoints. The tool for a tree that arrived from three different people with three different naming conventions.

• Click opens a dialog with the viewpoint tree on one side and the operation on the other: find and replace, plain or regular expression; a prefix and a suffix; sequential numbering with a start and a padding; or a case cleanup. A live preview shows the old and new name of every ticked item and flags collisions as it goes. Nothing is applied while the plan still has a collision or a problem. Applying renames the ticked items and toasts how many were renamed and how many failed. A document with no saved viewpoints gets a dialog saying so.

Deleter#

Bulk deletes saved viewpoints, empty folders and animations, which the saved-viewpoints tree does one at a time.

• Click opens a dialog where you search and tick, or pick items out by type, by being duplicates, or by having comments. It then asks for confirmation naming how many will go, because this removes them from the document, and deletes them as one operation, reporting what was removed and anything that failed.

Manager#

Sorts, reorganizes and cleans up the saved viewpoint folder tree. Where the Renamer fixes names, this fixes structure.

• Click opens a dialog that stays open and applies each action as you choose it, re-reading the tree afterwards so the next action is never planned against a stale picture: sort the tree A to Z, move ticked items into a folder, create a folder, or purge folders that hold no viewpoints. A move that is not legal, such as a folder into itself, is refused with a reason rather than half applied. The purge asks for confirmation naming how many folders it would remove.

Fit#

Fits the six section planes to the current selection, turned to the objects. Navisworks' own Fit Section to Selection gives a box square to the world, so a diagonal run of pipe gets four corners of empty space; this gives planes parallel to the run.

• Click sections to the selection and toasts the result.
• Shift+Click sets the two numbers both this and Plan use: the padding each plane stands off the objects, which starts at 150 mm so faces do not graze the geometry, and the snap angle, which starts at 1.5 degrees. Inside the snap angle the box stops turning and stays square to the world, because a two-degree tilt costs every plane's alignment and buys nothing. Both are validated as you type.
• Settings section_planes.json, shared with Plan.

Plan#

Fits the section planes the same way Fit does, then swings the camera to an orthographic plan of them. The camera turns with the box, so the objects sit square on screen rather than skewed across it.

• Click sections and reorients in one step.
• Settings the same section_planes.json as Fit. Plan has no Shift+Click action of its own, so change the padding and snap angle from Fit.

Clear#

Switches sectioning off without moving the camera, so you keep the view you worked to get and only lose the clipping.

Copy State#

Copies one kind of view state to disk for this document, so it can be put back later. The answer to setting up a section, a set of hidden items or a colour scheme and then needing to look at something else.

• Needs an open document.
• Click opens a small chromeless switch whose buttons are the question: section state, hidden items, or appearance overrides. Picking one copies that kind and toasts; cancelling says nothing. The copy is written under %APPDATA%\pyNavis\viewstate\ keyed to the document, so it is still there in another Navisworks session.

Paste State#

Puts back a kind of state copied earlier with Copy State, in this document.

• Needs an open document.
• Click offers only the kinds actually copied for this document. With nothing copied yet it says so in a dialog instead of showing an empty picker.

Reset Speeds#

Pushes your saved walk speed, turn speed and field of view at the view on screen. Navisworks resets navigation speed constantly, and this puts your numbers back in one keystroke.

• Needs an open document.
• Click applies whichever of the three are ticked in the settings and toasts what it changed. With all three switched off it says so rather than claiming a success. Field of view needs a perspective view, so in an orthographic one it warns and applies the two speeds only.
• Shift+Click opens the shared speeds window below.
• Shortcut Alt+Q.

Reset Viewpoints#

Writes the same three numbers into saved viewpoints you pick, so a set of views handed over by someone else navigates the way you expect when you recall them.

• Needs saved viewpoints in the document.
• Click opens the viewpoint browser, the same tree the Deleter and Manager use, with the values that are about to be written named at the top. Ticked views are rewritten without any of them being loaded: each saved item is copied, its camera edited, and the copy swapped back into place. The whole run is a single undo step and can be stopped part way from the progress window, which keeps whatever was written. The toast reports what was written and what was skipped: folders have no camera, animations keep theirs on their own cuts, views that already matched are counted, and on the rebuild route it says plainly that redlines and appearance overrides were not carried over.
• Shift+Click opens the shared speeds window below.
• Shortcut Alt+Z.

Viewpoint Tracker#

A dock panel that answers the question you ask all day in a review: which saved view am I looking at, and am I still on it? Two lines, live. The top line reads "Active viewpoint" while the camera still sits where the saved view put it and "Last viewpoint" once you have walked off, and the bottom line is the view's name, shrunk or grown to fit the panel.

• Click the ribbon button to show and hide the panel. The button is a toggle that follows the panel's own visibility, so closing the panel with its own close button leaves the button correct. Its keytip is VT.
• Click the name in the panel to go back to that view.
• With no document, or before any saved view has been current, it shows "No viewpoint selected" and no status line.

Two details are worth knowing because they are what make it trustworthy. It watches Navisworks directly rather than through a pyNavis hook, so it keeps updating while another pyNavis tool is running, and camera movement is collapsed into one repaint a quarter of a second after you stop moving rather than repainting per frame. The comparison against the saved camera allows a small tolerance, because recalling a view and reading the camera back moves the numbers in their last decimal places; real navigation moves them by far more, so nothing genuine is missed.

Section Nudge#

Moves the section box or planes from the keyboard instead of the drag handles. Dragging a handle in the view is imprecise and easy to overshoot; this pad moves a known distance per press, and every press is one undo step.

• Needs an open document. With sectioning off the panel says so and offers a button that switches it on in the current view.
• The panel is a dock panel toggled from the Viewpoints panel. It shows the target and where it is, seven target buttons (the box, then 1 to 6), a nudge pad, and the step with halve and double buttons and a box to type a value in the document's units. In Planes mode the six targets are the planes the Sectioning tab lists, and In moves one along its normal so less of the model is kept, Out the other way. In Box mode they are the six faces, +X, -X, +Y, -Y, +Z, -Z in the box's own frame, and In shrinks the box on that face, Out grows it; shrinking past the opposite face is refused. The box target moves all six planes together along the world axes.
• Keys, once the panel has focus: 0 to 6 pick a target and Tab cycles; Up and Down nudge a plane in and out; for the box, arrows move it in X and Y and Page Up and Page Down in Z; plus and minus double and halve the step; Enter applies a typed step. The readout follows changes made elsewhere, so dragging a handle and then nudging just works.
• Chords over the 3D view, no panel needed: Ctrl+Alt with Up and Down nudge in and out, with Left and Right change the target, and with Page Up and Page Down double and halve the step. Each is a chord-only bundle listed in the Shortcuts editor under its Nudge title, so it can be rebound or switched off, which matters on a machine where a graphics driver claims Ctrl+Alt with the arrow keys.
• State The target and step are session state shared by the panel and the chords; the planes themselves are always read fresh from the current viewpoint.

In the flyout: Tracker Window#

The same two lines in a floating window that stays on top of everything, for when the dock panel is in the way or you are walking the model with another application on screen. Both shells run the same code, so the panel and the window can never disagree.

• Click opens the window. Clicking the name goes back to that view, the same as in the panel. Clicking the button again focuses the window that is already open rather than stacking a second one on top of it, and there is no toast: an always-on-top window in the middle of the screen is its own report.

Where to go next#