• Dummy Article For Plugin Page

SB_Statistics_Probe    v2.0

  • Overview
  • Quick Start
  • Documentation
  • Release Notes

This extension probes the contents of a model and reports the number of edges and faces in individual objects, in descending order. Version 2.0 provides both visual and tabular versions.

Launch a version either from the Extensions/Statistics Probe submenu or from the tool bar. In both versions, the report starts with the "heaviest" (i.e. greatest number of edges) object in the current edit context (model, group, or component open for edit).

The visual version zooms and highlights a group or component and reports its number of contained edges and faces in a dialog. Press the right arrow key to report the next lighter object in the context, and the left arrow to return to the next heavier. Press the down arrow key to probe into the currently highlighted object's contents. The up arrow moves back to the parent container of the current context.

The tabular version opens a dialog containing a table of all the objects in the current context. This provides a faster overall view than the visual version, which is always one-by-one. Click on a row to drill down into that object's contents, and the up button to go back to the parent object context.

Launch either version of the extension by Extensions->Statistics Probe submenu or by clicking its toolbar/palette.

In the visual version, a dialog reporting the object with the largest edge count (the "heaviest") in the model will open. The view will zoom onto that object and a magenta highlight box will be drawn around it.

Press the right arrow key to shift the probe to the next lighter object in the model. Press the right arrow key to return to the next heavier object.

Press the down arrow key to recursively probe the contents of the currently reported object, for example to see which nested object contributes most to its weight. Left and right arrows work as before, but within this nested context only. Press the up arrow to return to the enclosing parent of the current context.

In the tabular version, a dialog reporting the edge counts of all the objects in the current edit context will be displayed, sorted in descending order of edge count. Click on a row to descend into that object's context. The Up button returns to the parent object's context.

Statistics Probe extension

The purpose of this extension is to facilitate finding which objects in a model contribute the most edges to its total and therefore have the greatest impact on SketchUp's performance. It is quite common for "entourage" elements from the 3D Warehouse to be seriously over-detailed compared to the rest of the model. These "heavy" objects cause SketchUp to become sluggish and modeling to become difficult. Once you know what is weighting down a model, you can take action to alleviate the issue, for example by simplifying the offending objects, substituting proxy objects during model editing or turning off visibility of heavy objects.

SketchUp's built-in tools do not provide useful support for this kind of model analysis. Model Info Statistics presents only the model-wide totals, with no indication of where they came from. Entity Info presents only information about the current edit selection, and not about edge counts unless you have selected a set of edges. The Outliner makes it easy to select a Group or Component, but tells you nothing about its statistics. The Component window's statistics tab will show you the details for a selected Component, but it does not provide a way to sort them based on their statistics. It can be tedious to find which Components are the troublemakers by looking at them one by one in this unsorted list. Also, the Component Window's statistics don't tell you if the model has become heavy due to a large number of copies of a Group or Component that has only a modest number of edges per copy.

This extension improves on these analyses. It adds up the edge counts recursively for each object in the current edit context (model, group, or component). multiplies them by the number of copies of a Group or Instances of a Component in the entire model, and sorts them in descending order. The counting across all contexts is deliberate: there might be numerous copies scattered over several contexts, and a count for only one context would mislead you as to the true impact of the object.

This extension includes two Tools that present the results in different ways:

1. Visual interactive version

This version zooms to and draws a magenta highlight box around the current target of analysis. A dialog box displays the statistics for that object. By pressing the arrow keys, you can navigate to the next lighter (right arrow) or next heavier (left arrow) in the same context. You can also probe into the details of the current group or component by pressing the down arrow, or go back out to the parent group or component by pressing the up arrow. The zoom and highlight actions are repeated each time one of these navigation actions is taken.

2. Tabular version

This version presents a table with a report row for each object in the currrent context. There is also a row for "loose edges", that is, edges drawn directly in the current context not grouped or in a component. The rows are sorted in descending order by their total edge counts. When you click on a row, the table is updated with the data for that group or component's edit context. Clicking the "Up" button returns to the parent context.

Tradeoffs between the two Tools

The visual version directly shows which object in the model is being reported. This is especially valuable for a model in which you have not given meaningful names to components, component instances or group instances. It can be difficult to identify which objects in the model correspond to names that SketchUp generated by default, such as "Group#23" or "Component#41". For Components, the Outliner displays the definition name as well as any instance name. For Groups it will display the instance name if there is any, but otherwise displays just "Group" for every object. So, the visual feedback helps you to see exactly where the problem lies even if you didn't provide usable nams. The visual version also offers an option to temporarily unhide or retag a non-visible object, avoiding any mystery about what is being reported.

The price of this feedback is that the zoom and unhide actions to show the current object involve exactly the kind of view changes that are slow in a "heavy" model. This penalty is paid each time you change the target of the analysis. As a result, on this Tool version each stage will be about as slow as user manipulation using the GUI. I have tested on several models of about 2 million edges and one with over 27 million edges. On the former the performance is acceptable, if a bit sluggish. On the latter the Tool works, but very slowly (often tens of seconds to complete an analysis).

The tabular version shows the sorted edge counts of everything in the current context, so when there is more than one problem object you can see them all at once without any further probing. You can also tell immediately when there is just one or multiple problem objects. It is much faster for these purposes than exploring the model with the visual version.

The initial analysis to build the data takes the same amount of time as for the visual version because it is the same calculation. But because this version does not manipulate the view, display of the results is nearly instantaneous. Probing into a row is usually much faster, partly because of not changing the view but also because there are usually far fewer contents in a single selected object than in the whole model.

To use the extension:

  1. Install the extension rbz using SketchUp's Extension Manager. It might be necessary to restart SketchUp next to get the extension to show up.

  2. The extension adds a submenu named "Statistics Probe" to the Extensions menu. It has two submenus corresponding to the two Tool versions. It also creates a toolbar (aka pallette on Mac) named 'Statistics Probe'. The toolbar has a button icon that looks like a scales for the visual Tool, and a button icon that looks like a table for the tabular Tool. Because they do not rely on you selecting anything, neither Tool version has its own cursor.

    Click one of these menu items or toolbar buttons to launch the Tool. A dialog box will open showing the initial results. Be patient - on a very heavy model it will take some time to perform the analysis, and SketchUp will be non-responsive during this period.

  3. The analysis will start with whatever edit context is currently open. If nothing is open, the start will be the whole model. But if a Group or Component is open for edit, the analysis will start with that edit context. This can be a useful way to reduce the analysis time if you are interested in just a particular part of the model. Note, however, that because another copy of a Group or another instance of a Component may be nested in a different parent context, when you start with a Group or Component open for edit, it is not possible to move up to its parent.

  4. Visual Tool Usage Details

    4.1 In some cases there may be some other object blocking the view of the highlighted object in the visual Tool. If you can't see any part of the highlight box, try activating X-ray mode to see if it is hiding behind something. If so, you may be able to orbit to look from a direction where there is no intervening object. The extension detects whether you have a shortcut set for X-ray and if so, uses the same. If you do not have a shortcut set, the extension defaults to "X". This keypress toggles back and forth between regular and X-ray.

    Note: for consistency with how shortcuts are shown in the SketchUp Preferences, the base character of the shortcut is always capitalized. If it is actually capital, the hint on the report dialog will say "Shift+X" on Windows and "⇧X" on Mac (or whatever other base key you used instead of X). Similarly, other standard prefixes are shown when other modifier keys are used.

    4.2 You can then explore additional objects in the current context by pressing the right arrow. This will move the highlight and dialog report to the object with the next highest edge count (the "next heaviest"). Pressing right arrow repeatedly will move to still further "lighter" objects until there are no more in the context. Pressing left arrow moves the report focus back to the next heavier object. Messageboxes will tell you when you reach the ends of the current context.

    4.3 If the next object is not visible, either because its hidden flag is set or because it uses a non-visible layer/tag, the extension will raise a dialog box asking whether you want to make that object visible. If you say no, the highlight box will still be shown and the statistics reported, though the box will be empty. If you say yes, the object will be unhidden or switched temporarily to a visible layer/tag so that you can see it. It will be re-hidden or returned to its original tag when you navigate away using any of the arrow keys.

    ==Note: The make visible applies only to the object itself. If its contents are hidden because of their own settings they will remain non-visible, though their edges and faces will be counted. You will need to investigate the contents per step 4.4 below.==

    4.4 When an object is highlighted and has other objects nested in it, you can press the down arrow to enter the highlighted object's nested context. If the only contents of the nested context are loose geometry (no Groups or Components), the extension will display a messagebox and will not enter that context. There is no need to do so because the edge count is already shown while reporting on the container object.

    The right and left arrows will then again move along the heaviness scale, but staying in this single context. And again, if the highlighted object has nested objects, down arrow will recursively enter its nest context.

    In a like manner, up arrow causes the analysis to move back out to the enclosing parent context until you return to the top-level of the model or the context that was open when you started the analysis.

  5. Tabluar Tool Usage Details

    5.1 The table dialog is scrollable, which is essential for complex models with many groups or components. However, depending on your OS settings, the scrollbars might not be visible. For example, on macOS in System Preferences->General you can choose between three ways that scrollbars are managed. For two of these, the scrollbars are hidden until you start a gesture or mouse action that causes a scroll.

    5.2 Click anywhere in a row of the table to refresh the report for the nested contents of the Group or Component displayed in that row. Click the "Up" button to return to the parent context (the containing Group or Component) for the current list. A message box will tell you when you click on a "loose edges" row because that is a count within the current context, not a nested context you can probe into. A message box will also tell you when the Up button has reached the starting context and can go no higher.

  6. You can quit the extension in any of several ways. You can click the "Quit" button in the report dialog (preferred). You can click the window close icon on the report dialog's title bar. Or you can click in the model view and then select a different tool. To the extent it can, the visual version "undoes" its manipulations of the model, including moving the camera, zooming, unhiding objects and changing an object's layer/tag to make it visible.

    ==Despite undoing them, SketchUp leaves the extension's operations on the model's redo stack, and that will cause the model to show as modified even if it was restored perfectly. The SketchUp Ruby API does not provide access to the stack, so there is nothing I can to to mark the model as unchanged or to purge these operations from redo. However, like undo information, they are discarded when you save the model.==

There is a known issue on Windows:

==If you click on the view anywhere outside the visual Tool's dialog, use the mouse to orbit, pan, or zoom the model, or press the return key in a messagebox, the focus does not auatomatically return to the dialog. As a result, the arrow key handling ceases until you refocus the dialog by clicking anywhere in it. This is a known issue with the SketchUp HtmlDialog class on Windows, with no known universal workaround. It does not happen on Mac.==


==Because it deeply probes the model and manipulates the view, the performance of the extension is affected by the complexity of the model in much the same way as SketchUp itself. On a very heavy model it may take tens of seconds to complete a step depending on your computer, but it should eventually complete. It was tested on a model with over 27 million edges and worked correctly though slowly. Be patient if your model is extreme!==

Other known issues:

The visual version does not deal well with locked objects. If your model relies on locked objects you may need to unlock them to get correct results.

I welcome your feedback on anything from wording to bugs to suggestions for improvement!! steve@slbaumgartner.com

July 11, 2020: Initial release version 1.0

March 29, 2021: version 2.0 added tabular version