0031337: Inspectors - user guide update
[occt.git] / dox / user_guides / inspector / inspector.md
1 Inspector  {#occt_user_guides__inspector}
2 ===============================
3
4 @tableofcontents
5  
6 @section occt_inspector_1 Introduction
7
8 This manual explains how to use the Inspector.
9
10 @subsection occt_inspector_1_1 Overview
11 Inspector is a Qt-based library that provides functionality to interactively inspect low-level content of the OCAF data model, OCCT viewer and Modeling Data.
12 This component is aimed to assist the developers of OCCT-based applications to debug the problematic situations that occur in their applications.
13
14 Inspector has a plugin-oriented architecture. The current release contains the following plugins:
15
16 | Plugin | OCCT component | Root class of OCCT investigated component |
17 | :----- | :----- | :----- |
18 | @ref occt_inspector_2_2 "DFBrowser"| OCAF | *TDocStd_Application* |
19 | @ref occt_inspector_2_3 "VInspector"| Visualization | *AIS_InteractiveContext* |
20 | @ref occt_inspector_2_4 "ShapeView"| Modeling Data | *TopoDS_Shape* |
21 | @ref occt_inspector_2_5 "MessageView"| Modeling Data | *Message_Report* |
22
23
24 Each plugin implements logic of a corresponding OCCT component.
25
26 Each of the listed plugins is embedded in the common framework, thus it is possible to manage, which plugins should be loaded by the Inspector, and to extend their number by implementing a new plugin.
27
28
29 @subsection occt_inspector_1_3 Getting started
30
31 There are two launch modes:
32 1. Launch **TInspectorEXE** executable sample. For more details see @ref occt_inspector_4_1 "TInspectorEXE" section;
33 2. Launch DRAW, load plugin INSPECTOR, and use *tinspector* command.
34    For more details, see @ref occt_inspector_4_2 "Launch in DRAW Test Harness" section.
35
36
37 **Note**. If you have no Inspector library in your build directory, make sure that OCCT is compiled with *BUILD_Inspector* 
38 option ON. For more details see @ref occt_inspector_5 "Build procedure".
39
40
41 @section occt_inspector_2 Inspector Plugins
42
43 @subsection occt_inspector_2_1 Overview
44
45 Inspector consists of the following components:
46   * <b>buttons</b> to activate the corresponding plugin;
47   * <b>view area</b> to visualize the plugin content.
48
49 @figure{tinspector_elements.svg,"Plugins placement in Inspector",360}
50
51 @subsection occt_inspector_2_2 DFBrowser Plugin
52
53 @subsubsection occt_inspector_2_2_1 Overview
54
55 @figure{dfbrowser.png, "DFBrowser"}
56
57 This plugin visualizes the content of *TDocStd_Application* in a tree view. It shows application documents, 
58 the hierarchy of *TDF_Labels*, the content of *TDF_Attributes* and interconnection between attributes (e.g. references).
59 Additionally there is a 3D view to visualize *TopoDS_Shape* elements stored in the document.
60
61 @subsubsection occt_inspector_2_2_2 Elements
62
63 @figure{dfbrowser_elements.svg, "DFBrowser Elements",360}
64
65 <b>OCAF tree view</b>
66
67 Each OCAF element has own tree view item:
68
69 | Type | Tree item | Text | Description |
70 | :----- | :----- | :----- | :----- |
71 | *TDocStd_Application* | Application | *TDocStd_Application* | The root of tree view. Its children are documents.|
72 | *TDocStd_Document* | Document | entry : name | A child of *Application* item. Its children are *Label* and *Attribute* items.<br> Text view is an entry of the root label and the value of *TDataStd_Name* attribute for the label if it exists. |
73 | *TDF_Label* | Label | entry : name | A child of a *Document* or another *Label* item. Its children and text view are the same as for Document item. |
74 | *TDF_Attribute* | Attribute | attribute type [additional information] | A child of a *Label*. It has no children. <br> Text view is the attribute type *(DynamicType()->Name()* of *TDF_Attribute*) and additional information (a combination of attribute values). |
75
76
77 Additional information about TDF_Attributes:
78
79 | Type | Text |
80 | :----- | :----- |
81 | *TDocStd_Owner* | [storage format] |
82 | *TDataStd_AsciiString*,<br> *TDataStd_Name*,<br> *TDataStd_Real*,<br> other *Simple* type attributes | [value] |
83 | *TDataStd_BooleanList*,<br> *TDataStd_ExtStringList*,<br> other *List* attributes | [value_1 ... value_n] |
84 | *TDataStd_BooleanArray*,<br> *TDataStd_ByteArray*,<br> other *Array* type attributes | [value_1 ... value_n] |
85 | *TDataStd_TreeNode* | [tree node ID  ==> Father()->Label()] (if it has a father) or <br> [tree node ID <== First()->Label()] (if it has NO father)|
86 | *TDataStd_TreeNode(XDE)* | [XDE tree node ID  ==> Father()->Label()] (if it has a father), <br> [XDE tree Node ID <== label_1, ..., label_n] (if it has NO father)|
87 | *TNaming_NamedShape* | [shape type : evolution] |
88 | *TNaming_UsedShapes* | [map extent] |
89
90
91 Custom color of items:
92
93 | OCAF element Type | Color |
94 | :----- | :----- |
95 | *TDF_Label* | <b>dark green</b>, if the label has *TDataStd_Name* attribute, <br><b>light grey</b> if the label is empty (has no attributes on all levels of  hierarchy),<br> <b>black</b> otherwise. |
96 | *TNaming_NamedShape* | <b>dark gray</b> for *TopAbs_FORWARD* orientation of *TopoDS_Shape*, <br> <b>gray</b> for *TopAbs_REVERSED* orientation of *TopoDS_Shape*, <br> <b>black</b> for other orientation. |
97
98
99 Context pop-up menu:
100 | Action | Functionality |
101 | :----- | :----- |
102 | Expand | Expands the next two levels under the selected item. |
103 | Expand All | Expands the whole tree of the selected item. |
104 | Collapse All | Collapses the whole tree of the selected item. |
105
106 <b>Property Panel</b>
107
108 Property panel is used to display the result of <b>TDF_Attribute::Dump()</b> or <b>TDF_Label::Dump()</b> of the selected tree view item.
109 The information is shown in one table.
110
111 @figure{property_panel.png,"PropertyPanel",360}
112
113 <b>Property Panel (custom)</b>
114
115 Property panel (custom) is used to display the content of *Label* or *Attribute* tree view items or Search result view.
116 The information is usually shown in one or several tables.
117
118 *TDF_Attribute* has the following content in the Property Panel:
119
120 <table>
121 <tr><th>Type</th><th>Description</th><th>Content</th></tr>
122 <tr><td><i>TDF_Label</i></td>
123     <td> a table of [entry or attribute name, value]</td>
124     <td>@figure{property_panel_custom_label.png, "",140}</td></tr>
125 <tr><td><i>TDocStd_Owner</i>,<br> Simple type attributes, <br> List type attributes</td>
126     <td>a table of [method name, value]</td>
127     <td>@figure{property_panel_custom_simple_type.png, "",140}</td></tr>
128 <tr><td><i>TDataStd_BooleanArray</i>,<br> <i>TDataStd_ByteArray</i>,<br> other Array type attributes</td>
129     <td>2 controls: <br> - a table of [array bound, value], <br> - a table of [method name, value] </td>
130     <td>@figure{property_panel_custom_array.png, "",140}</td></tr>
131 <tr><td><i>TDataStd_TreeNode</i></td>
132     <td>2 controls: <br> - a table of [Tree ID, value] (visible only if Tree ID() != ID() ), <br> - a tree view of tree nodes starting from *Root()* of the tree node. The current tree node has <b>dark blue</b> text.</td>
133     <td>@figure{property_panel_custom_tree_node.png, "",140} </td></tr>
134 <tr><td><i>TDataStd_NamedData</i></td>
135     <td>tab bar of attribute elements, each tab has a table of [name, value]</td>
136     <td>@figure{property_panel_custom_named_data.png, "",140}</td></tr>
137 <tr><td><i>TNaming_UsedShapes</i></td>
138     <td>a table of all shapes handled by the framework</td>
139     <td>@figure{property_panel_custom_tnaming_used_shapes.png, "",140}</td></tr>
140 <tr><td><i>TNaming_NamedShape</i></td>
141     <td>2 controls: <br> - a table of [method name, value] including CurrentShape/OriginalShape methods result of <i>TNaming_Tools</i>, <br> - an evolution table. <br> Tables contain buttons for @ref occt_shape_export "TopoDS_Shape export".</td>
142     <td>@figure{property_panel_custom_tnaming_named_shape.png, "",140}</td></tr>
143 <tr><td><i>TNaming_Naming</i></td>
144     <td>2 controls: <br> - a table of <i>TNaming_Name</i> values,<br> - a table of [method name, value]</td>
145     <td>@figure{property_panel_custom_tnaming_naming.png, "",140}</td></tr>
146 </table>
147
148
149 <b>Dump view</b>
150
151 @figure{dump_attribute.png, "Dump of TDF_Attribute",200}
152
153 Dump view shows the result of <b>TDF_Attribute::Dump()</b> or <b>TDF_Label::Dump()</b> of the selected tree view item.
154
155 <b>3D view</b>
156
157 3D View visualizes *TopoDS_Shape* elements of OCAF attribute via AIS facilities.
158
159 DFBrowser creates two kinds of presentations depending on the selection place:
160
161 <table>
162 <tr><th>Kind</th><th>Source object</th><th>Visualization properties</th><th>View</th></tr>
163 <tr><td>Main presentation</td>
164     <td>Tree view item:<br> *TPrsStd_AISPresentation*,<br> *TNaming_NamedShape*,<br> *TNaming_Naming*</td>
165     <td>Color: a default color for shape type of the current *TopoDS_Shape*.</td>
166     <td>@figure{display_main_presentation.png, "",100}</td></tr>
167 <tr><td>Additional presentation</td>
168     <td>References in Property panel</td>
169     <td>Color: white</td>
170     <td>@figure{display_additional_presentation.png, "",100}</td></tr>
171 </table>
172
173
174
175 <b>Tree Navigation</b>
176
177 Tree Navigation shows a path to the item selected in the tree view.
178 The path is a sequence of label entries and attribute type names.
179 Each element in the path is selectable - simply click on it to select the corresponding tree view item.
180
181 Navigation control has buttons to go to the previous and the next selected tree view items.
182
183
184 <b>Update Button</b>
185
186 Update button synchronizes content of tree view to the current content of OCAF document that could be modified outside.
187
188 <b>Search</b>
189
190 The user can search OCAF element by typing:
191   * *TDF_Label* entry,
192   * *TDF_Attribute* name,
193   * *TDataStd_Name* and *TDataStd_Comment* attributes value.
194
195 @figure{search.png,"Search",360}
196
197 As soon as the user confirms the typed criteria, the Property panel is filled by all satisfied values.
198 The user can click a value to highlight the corresponding tree view item. By double click the item will be selected.
199
200
201 @subsubsection occt_inspector_2_2_3 Elements cooperation
202
203 <b>Tree item selection</b>
204
205 Selection of tree view item updates content of the following controls:
206   * Navigation line;
207   * Property Panel;
208   * 3D View (if it is possible to create an interactive presentation);
209   * Dump View.
210
211 @figure{dfbrowser_selection_in_tree_view.svg,"",360}
212
213 <b>Property Panel (custom) item selection </b>
214
215 If the property panel (custom) shows content of *TDF_Label*:
216   * selection of the table row highlights the corresponding item in the tree view,
217   * double click on the table row selects this item in the tree view.
218
219 If the property panel (custom) shows content of *TDF_Attribute* that has reference to another attribute, selection of this reference:
220   * highlights the referenced item in the tree view,
221   * displays additional presentation in the 3D view if it can be created.
222
223 @figure{property_panel_custom_item_selection.svg,"",360}
224
225 Attributes having references:
226
227 | Type | Reference | Additional presentation
228 | :----- | :----- | :----- |
229 | *TDF_Reference* | *TDF_Label* | |
230 | *TDataStd_ReferenceArray*, <br> *TDataStd_ReferenceList*, <br> *TNaming_Naming* | One or several *TDF_Label* in a container. | |
231 | *TDataStd_TreeNode* | *TDF_Label* | |
232 | *TNaming_NamedShape* | *TDF_Label* in Evolution table |  *TopoDS_Shapes* selected in the property panel tables. |
233 | *TNaming_UsedShapes* | one or several *TNaming_NamedShape* | *TopoDS_Shapes* of the selected *TNaming_NamedShape*. |
234
235
236 @subsubsection occt_shape_export TopoDS_Shape export
237
238 Property panel of *TNaming_NamedShape* attribute has controls to export *TopoDS_Shape* to:
239   * BREP. **Save file** dialog is open to enter the result file name,
240   * @ref occt_inspector_2_4 "ShapeView" plugin. The dialog for exporting element to ShapeView allows activating this plugin immediately.
241
242
243 @subsection occt_inspector_2_3 VInspector Plugin
244
245 @subsubsection occt_inspector_2_3_1 Overview
246
247 @figure{vinspector.png, "VInspector",360}
248
249 This plugin visualizes interactive objects displayed in *AIS_InteractiveContext* in a tree view with computed selection
250 components for each presentation. It shows the selected elements in the context and allows selecting these elements.
251
252 @subsubsection occt_inspector_2_3_2 Elements
253
254 @figure{vinspector_elements.svg,"VInspector Elements",360}
255
256 <b>Presentations tree view</b>
257
258 This view shows presentations and selection computed on them. Also, the view has columns with information about the state of visualization elements.
259
260 VInspector tree items.
261
262 | Type | Description |
263 | :----- | :----- |
264 | *AIS_InteractiveContext* | The root of tree view. Its children are interactive objects obtained by *DisplayedObjects* and *ErasedObjects* methods.|
265 | *AIS_InteractiveObject* | A child of *AIS_InteractiveContext* item. Its children are *SelectMgr_Selection* obtained by iteration on *CurrentSelection*.  |
266 | *SelectMgr_Selection* | A child of *AIS_InteractiveObject*. Its children are *SelectMgr_SensitiveEntity* obtaining by iteration on *Sensitive*. |
267 | *SelectMgr_SensitiveEntity* | A child of *SelectMgr_Selection*. Its children are *SelectMgr_SensitiveEntity* obtaining by iteration on *OwnerId*. |
268 | *SelectBasics_EntityOwner* | A child of *SelectMgr_SensitiveEntity*. It has no children. |
269
270
271 Custom color of tree view items:
272
273 | OCAF element Type | Column | What | Color |
274 | :----- | :----- | :----- | :----- |
275 | *AIS_InteractiveObject* | 0 | Text | <b>dark gray</b> in *ErasedObjects* list of *AIS_InteractiveContext*,<br> <b>black</b> otherwise |
276 | *AIS_InteractiveObject*, <br> *SelectMgr_SensitiveEntity*, <br> *SelectBasics_EntityOwner*| 1 | Background | <b>dark blue</b>, if there is a selected owner under the item, <br> <b>black</b> otherwise |
277 | *SelectMgr_Selection*,<br> *SelectMgr_SensitiveEntity*,<br> *electBasics_EntityOwner* | all | Text | <b>dark gray</b>, if *SelectionState* of *SelectMgr_Selection* is not *SelectMgr_SOS_Activated*,<br> <b>black</b> otherwise |
278
279
280 Context popup menu in tree view:
281 | Action | Item | Functionality |
282 | :----- | :----- | :----- |
283 | Export to ShapeView | *AIS_InteractiveObject* | Exports *TopoDS_Shape* of the *AIS_Interactive* presentation to ShapeView plugin. <br> It should be *AIS_Shape* presentation and ShapeView plugin should be registered in Inspector<br> Dialog about exporting element to ShapeView is shown with a possibility to activate this plugin immediately. |
284 | Show | *AIS_InteractiveObject* | Displays presentation in *AIS_InteractiveContext*. |
285 | Hide | *AIS_InteractiveObject* | Erases presentation from *AIS_InteractiveContext*. |
286
287 <b>Update</b>
288
289 This button synchronizes the plugin content with the current state of *AIS_InteractiveContext* and updates the presence of items and their current selection.
290
291 @subsubsection occt_inspector_2_3_3 Elements cooperation
292
293 *VInspector* marks the presentations currently selected in *AIS_InteractiveContext* with a blue background in tree items. Use **Update** button to synchronize VInspector selected items state to the context.
294
295 It is also possible to perform selection in the context using "Selection controls" VInspector feature. However, this operation should be performed carefully as
296 it clears the current selection in *AIS_InteractiveContext*.
297
298 Selection change:
299 | From | To | Action | Result |
300 | :----- | :----- | :----- | :----- |
301 | *AIS_InteractiveContext* | VInspector | Performs selection in *AIS_InteractiveContext*. | Click **Update** button in VInspector and check **Selection** column: <br> *AIS_InteractiveContext* item contains some selected objects, <br> the value of some *AIS_InteractiveObject* is filled if they are selected for this presentation or its entity owner. |
302 | VInspector | *AIS_InteractiveContext* | Activates one of Selection controls and selects one or several elements in the tree view. | The objects become selected in *AIS_InteractiveContext*. |
303
304 @subsubsection occt_inspector_2_3_4 VInspector tree view columns
305
306 Use context pop-up menu on the tree view header to select, which columns should be displayed.
307 @figure{vinspector_tree_columns.png, "Vinspector tree header context menu",360}
308
309 Use the setting Lights (position, color) in the view.
310 @figure{vinspector_light_setting.png, "Vinspector light setting",360}
311
312 @subsubsection occt_inspector_2_3_5 VInspector property panel
313
314 Property panel shows the result of <b>AIS_InteractiveContext::Dump()</b> or <b>AIS_InteractiveObject::Dump()</b>.
315 @figure{vinspector_property_panel.png, "Vinspector property panel",360}
316
317 @subsection occt_inspector_2_4 ShapeView Plugin
318
319 @subsubsection occt_inspector_2_4_1 Overview
320
321 @figure{shapeview.png, "ShapeView",360}
322
323 This plugin visualizes content of *TopoDS_Shape* in a tree view.
324
325 @subsubsection occt_inspector_2_4_2 Property panel
326
327 Property panel shows properties for TopoDS_Shape based on DumpJson.
328
329 @figure{shapeview_property_panel.png, "ShapeView Property panel",360}
330
331 @subsubsection occt_inspector_2_4_3 Elements
332
333 @figure{shapeview_elements.svg,"ShapeView Elements",360}
334
335 <b>TopoDS_Shape View</b>
336
337 The view elements are *TopoDS_Shape* objects.
338 The shape is exploded into sub-shapes using *TopoDS_Iterator* of the *TopoDS_Shape*.
339 Children sub-shapes are presented in the view as children of the initial shape.
340 By iterating recursively through all shapes we obtain a tree view of items shown in the ShapeView.
341
342 The columns of the View show some information about *TopoDS_Shape* of the item.
343 The first column allows changing the visibility of the item shape in the 3D view.
344
345 Context pop-up menu in tree view:
346 | Action | Functionality |
347 | :----- | :----- |
348 | Load BREP file | Opens the selected file and appends the resulting *TopoDS_Shape* into the tree view. |
349 | Remove all shape items | Clears tree view. |
350 | BREP view | Shows the text view with BREP content of the selected item. Creates the BREP file in a temporary directory of the plugin. |
351 | Close All BREP views | Closes all opened text views. |
352 | BREP directory | Displays the folder, where temporary BREP files have been stored. |
353
354 @subsubsection occt_inspector_2_4_4 Elements cooperation
355
356 Selection of one or several items in *TopoDS_Shape* View creates its *AIS_Shape* presentation and displays it in the 3D View.
357
358 @subsubsection occt_inspector_2_4_5 ShapeView tree view columns
359
360 Use context pop-up menu on the tree view header to select, which columns should be displayed.
361 @figure{shapeview_tree_columns.png, "ShapeView tree header context menu",360}
362
363 @subsection occt_inspector_2_5 MessageView Plugin
364
365 MessageView plugin is used to display content of Message_Report.
366
367 @subsubsection occt_inspector_2_5_1 Message report tree view
368
369 Message report tree view shows the content of the Message_Report.
370
371 Context pop-up menu in message report tree view:
372 | Action | Functionality |
373 | :----- | :----- |
374 | Export Report | Exports the report as json file. |
375 | WallClock Metric statistic | Creates the table  that sums the number of calls and the time spent on the functionality inside the value and shows it in Property panel (custom). It's necessary to activate "WallClock metric". |
376 | Preview children presentations | Displays presentations of children items of selected items if found. |
377 | Deactivate | Deactivates all types of metrics for the current report. |
378 | Activate | Appends items to activate report metrics. |
379 | Clear | Clears message report. |
380 | Activate metric | Switches active state in report for clicked type of metric. |
381 | Test metric | Sends several alerts to check metric of message-alert-tool mechanism. |
382 | Test Message_Messenger | Sends several alerts to check property panel/presentations of messenger-alert-tool mechanism. |
383 | Test Tree of messages | Sends several alerts to check tree of alerts. |
384
385 @figure{messageview_pop_up_menu.png, "MessageView pop-up menu",360}
386
387 @subsubsection occt_inspector_2_5_2 3D View
388
389 3D View shows the selected item (TopoDS_Shape) in message report tree view.
390 @figure{messageview_view.png, "MessageView 3D View",360}
391
392 @subsubsection occt_inspector_2_5_3 Dump panel
393
394 Shows Dump() information of the selected item if the item has Dump().
395 @figure{messageview_dump_panel.png, "MessageView 3D View",360}
396
397 @subsubsection occt_inspector_2_5_4 Property panel (custom)
398
399 Shows the table for WallClock Metric statistic option.
400 @figure{messageview_property_panel_custom.png, "MessageView 3D View",360}
401
402 @subsubsection occt_inspector_2_5_5 Elements
403 @figure{messageview_elements.svg, "MessageView elements",360}
404
405 @section occt_inspector_3 Common controls
406
407 @subsection occt_inspector_3_1 Tree View
408
409 This control shows presentation hierarchy of the investigated OCCT element, e.g. *TDocStd_Application* for DFBrowser, see @ref occt_inspector_1_1 "Overview".
410 The first column contains the name, other columns are informative.
411
412 The tree view has a context menu with plugin-specific actions.
413
414 @subsubsection occt_inspector_3_1_1 Tree View preferences
415
416 It is possible to define visibility and width of columns.
417 This option is available in a view that contains more than one column,
418  e.g. @ref occt_inspector_2_3_4 "VInspector tree view columns"
419  and @ref occt_inspector_2_4_4 "ShapeView tree view columns".
420
421 @figure{treeview_preferences.svg, "Preferences schema",360}
422
423
424 @subsection occt_inspector_3_2 3D View
425
426 @subsubsection occt_inspector_3_2_1 Overview
427
428 @figure{3DView.png, "3D View",360}
429
430 This control for OCCT 3D viewer creates visualization view components and allows performing some user actions in the view.
431
432
433 @subsubsection occt_inspector_3_2_2 Elements
434
435 @figure{3DView_elements.svg,"3DView Elements",360}
436
437 3D View contains the following elements:
438 | Element | Functionality |
439 | :----- | :----- |
440 | 3D view | V3d viewer with mouse events processing. |
441 | Context | Allows choosing another context that should be used in the plugin. The following contexts are available:<br> **Own** - the context of this view, <br> **External** - the context of the @ref occt_inspector_4_3 "external application", which initializes the plugin, <br> **None** - the visualization is not performed at all (useful if the presentation is too complex). |
442 | Multi/Single | The buttons define what to do with the previously displayed objects: <br> **Multi** displays new presentations together with already displayed ones, <br> **Single** removes all previously displayed presentations. |
443 | Clean | Removes all displayed presentations. |
444 | Trihedron display | Shows the trihedron. |
445 | View cube display | Shows the view cube. |
446 | Fit All | Scene manipulation actions<br> (Fit All is checkable. If checked(by double click), display/hide of new objects will perform **Fit All** of the scene.) |
447 | Display Mode | Sets *AIS_Shading* or *AIS_WireFrame* display mode for all presentations. |
448
449 Context popup menu:
450 | Action | Functionality |
451 | :----- | :----- |
452 | Set View Orientation | Shows the list of available *V3d_View* projections. Selection of an item with change the view. |
453
454 @figure{3DView_set_orientation.png,"Set view orientation",360}
455
456 @subsubsection occt_inspector_3_2_3 3D View preferences.
457 View preferences store the current view orientation.
458
459 @subsection occt_inspector_3_3 Preferences context menu
460
461 @figure{preferences.png,"Plugin preferences",360}
462
463 Context menu contains:
464 | Element | Functionality |
465 | :----- | :----- |
466 | Tree Level Line,<br> PropertyPanel,<br> PropertyPanel (custom),<br> Dump, <br> View| Names of dock widgets in the active plugin. If the button is checked, dock widget is visible. |
467 | Store Preferences | Creates ".tinspector.xml" preferences file with the current settings for each plugin.<br> This file is created in TEMP/TMP directory (by default) or in a user-defined directory. |
468 | Remove Preferences | Removes preferences file. After the Inspector is restarted, default values will be applied. |
469
470
471 The following controls have store/restore preferences:
472 | Element | Preferences |
473 | :----- | :----- |
474 | Geometry| Inspector window size and position. <br>State of dockable widgets : visibility, position, size.|
475 | @ref occt_inspector_3_1_1 "Tree View preferences"| Columns visible in the tree view and their width. |
476 | @ref occt_inspector_3_2_3 "3D View preferences"| 3D view camera direction. |
477
478 @section occt_inspector_4 Getting Started
479
480 @subsection occt_inspector_4_1 TInspectorEXE sample
481
482 This sample allows trying Inspector functionality.
483
484 Use *inspector.bat* script file placed in a binary directory of OCCT to launch it.
485
486 This script accepts the names of plugin's DLL that should be loaded. By default it loads all plugins described above.
487
488
489 @figure{TStandaloneEXE.png, "TStandaloneEXE",360}
490
491 Click on the Open button shows the dialog to select a file.
492 @figure{TStandaloneEXE_open.png, "",360}
493
494 Depending on the active plugin, it is possible to select the following files in the dialog:<br>
495 - DFBRowser: OCAF document or STEP files;
496 - VInspector: BREP files;
497 - ShapeView: BREP files.
498
499 Click the file name in the proposed directory and enter it manually or using **Browse** button.
500
501 By default, TInspectorEXE opens the following files for plugins:
502 | Plugin DLL library name | Files |
503 | :----- | :----- |
504 | TKDFBrowser | step/screw.step |
505 | TKVInspector | occ/hammer.brep |
506 | TKShapeView | occ/face1.brep, <br> occ/face2.brep |
507
508 These files are found relatively to *CSF_OCCTDataPath*.
509
510 @subsubsection occt_inspector_4_1_1 TInspectorEXE preferences
511 The application stores recently loaded files. On the application start, the last file is activated.
512 **Open file** dialog contains recently loaded files.
513 Selection of a new file updates the container of recently loaded files and rewrites preferences.
514
515 Source code of *TIspectorEXE* is a good sample for @ref occt_inspector_4_3 "using the Inspector in a custom application".
516
517 @subsection occt_inspector_4_2 How to launch the Inspector in DRAW Test Harness
518
519 *TKToolsDraw* plugin provides DRAW commands for Qt tools. Use *INSPECTOR* parameter of @ref occt_draw_1_3_3 "pload" 
520 command to download the commands of this library. It contains *tinspector* command to start Inspector under DRAW.
521 See more detailed description of the @ref occt_draw_13_1 "tinspector" command.
522
523 The simple code to start Inspector with all plugins loaded:
524
525 ~~~~
526 pload INSPECTOR
527 tinspector
528 ~~~~
529
530 @figure{drawexe_tinspector.png,"tinspector",360}
531
532 This command does the following:
533 - all available Plugins are presented in the Inspector. These are @ref occt_inspector_2_2 "DFBrowser", @ref occt_inspector_2_3 "VInspector", @ref occt_inspector_2_4 "ShapeView" and  @ref occt_inspector_2_5 "MessageView";
534 - DFBrowser is the active plugin;
535 - OCAF tree is empty.
536
537 After this, we should create objects in DRAW and update *tinspector*.
538 The examples of using Inspector in DRAW can be found in OCCT source directory /tests/tools.
539
540 @subsection occt_inspector_4_3 How to use the Inspector in a custom application
541
542 The example of using the Inspector in a custom application is presented in OCCT qt sample - <b>FuncDemo</b>.
543 For building qt samples, switch on *BUILD_SAMPLES_QT* variable in @ref build_cmake_conf "Configuration process".
544
545 In general, the following steps should be taken:
546 * Set dependencies to OCCT and Qt in the application (Header and Link);
547 * Create an instance of *TInspector_Communicator*;
548 * Register the plugins of interest in the communicator by DLL library name;
549 * Initialize the communicator with objects that will be investigated;
550 * Set visible true for the communicator.
551
552
553
554 Here is an example of C++ implementation:
555 ~~~~{.cpp}
556
557 #include <inspector/TInspector_Communicator.hxx>
558
559 static TInspector_Communicator* MyTCommunicator;
560
561 void CreateInspector()
562 {
563   NCollection_List<Handle(Standard_Transient)> aParameters;
564   //... append parameters in the list
565
566   if (!MyTCommunicator)
567   {
568     MyTCommunicator = new TInspector_Communicator();
569
570     MyTCommunicator->RegisterPlugin ("TKDFBrowser");
571     MyTCommunicator->RegisterPlugin ("TKVInspector");
572     MyTCommunicator->RegisterPlugin ("TKShapeView");
573     MyTCommunicator->RegisterPlugin ("TKMessageView");
574
575     MyTCommunicator->Init (aParameters);
576     MyTCommunicator->Activate ("TKDFBrowser");
577   }
578   MyTCommunicator->SetVisible (true);
579 }
580 ~~~~
581
582 Give one the following objects for a plugin using a container of parameters:
583
584 | Plugin | to be initialized by |
585 | :----- | :----- |
586 | *TKDFBrowser* | *TDocStd_Application* |
587 | *TKVInspector* | *AIS_InteractiveContext* |
588 | *TKShapeView* | *TopoDS_TShape* |
589 | *TKMessageView* | *Message_Report* |
590
591
592 @section occt_inspector_5 Build procedure
593
594
595 @subsection occt_inspector_5_1 Building with CMake within OCCT
596
597 By default the Inspector compilation is off.
598 To compile it, set the *BUILD_Inspector* flag to "ON". See @ref build_cmake_conf "Configuration process".
599
600 When this option is switched ON, MS Visual Studio project has an additional tree of folders:
601
602 @figure{VStudio_projects.png,"Inspector packages in MS Visual Studio",160}
603
604
605 @section occt_inspector_6 Sources and packaging
606
607 OCCT sources are extended by the /tools directory.
608
609 Distribution of plugin packages :
610 | Source packages | Plugin |
611 | :----- | :----- |
612 | *DFBrowser*, <br> *DFBrowserPane*, <br> *DFBrowserPaneXDE*, <br> *TKDFBrowser* | DFBrowser |
613 | *VInspector*, <br> *TKVInspector*  | VInspector |
614 | *ShapeView*, <br> *TKShapeView* | ShapeView |
615 | *MessageView*, <br> *TKMessageView* | MessageView |
616
617 Other packages:
618 | Source packages| Used in |
619 | :----- | :----- |
620 | *TInspectorAPI*, <br> *TKInspectorAPI* | Interface for connection to plugin. |
621 | *ViewControl*, <br> *TKTreeModel* | Classes for property view, table, table model. |
622 | *TreeModel*, <br> *TKTreeView* | Items-oriented model to simplify work with GUI tree control. |
623 | *View*, <br> *TKView* | 3D View component. |
624 | *TInspector*, <br> *TKTInspector*  | Inspector window, where plugins are placed. |
625 | *ToolsDraw*, <br> *TKToolsDraw* | Plugin for DRAW to start Inspector. |
626
627
628 In MSVC studio, a separate folder contains Inspector projects.
629
630 @section occt_inspector_7 Glossary
631 * **Component** -- a part of OCCT , e.g. OCAF, VISUALIZATION, MODELING and others. 
632 * **Plugin** -- a library that is loaded in some executable/library. Here, the plugins are:
633   * DFBrowser,
634   * ShapeView,
635   * VInspector.