GroIMP wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Post processing a QSM with GUI tools ======

This tutorial explains the workflow of the GUI tools provided by the QSM plugin, based on some example actions. All this functionalities work not only on imported QSM but on DTD or fastrak xml files.


===== Requirements =====

This tutorial requires GroIMP 2.2.1 or higher and the QSM plugin of version 2.2.2 or higher as well as the coolbar plugin.



==== Preparations ====

To ease the usage of the QSM GUI tools, we want to configure the node toolbar to show more buttons at the same time. To do so please go on 'Panels > Preferences', select 'coolbar > nodetoolbar' and set the value of groupNum to 15.


===== Loading the QSM =====

Loading a QSM file in GroIMP is possible in two ways either it can be opened as new project, which creates an empty workbench with only the qsm loaded, or by importing it to an existing project.

An example qsm file can be found here: {{ :tutorials:qsm:example_qsm.qsm |}}

==== Open as new project ====

If the QSM plugin is installed a .qsm file can be opened from the GroIMP main menu: 'Files > Open...'
The project created from this will start automatically in the QSM layout providing the QSM inspector and the Node toolbar 3d. Yet this project has not RGG runtime and can therefore not execute any code, it is purely usable through GUI interaction. 

For this tutorial this way is sufficient and suggested.

==== Import to existing project ====

In order to add a .qsm file to an existing project the normal way of importing can be used(
see: [[tutorials:import-object-in-groimp|Import objects in GroIMP]]). 

To manipulate so imported tree using the qsm GUI tools, please switch to the QSM-layout: in the main menu on 'Panels/Set Layout/QSM Layout'.


===== First look =====

{{ :tutorials:qsm:open_first_look.gif|}}

After opening the qsm file, lets first use the color coding function to high lite the different branching orders. This can be done in the edit menu on 'Edit > QSM > Color code'. 
To get a better overview lets also hide all orders higher than 2 using 'Edit > QSM > Show/Hide > Hide higher'. This function renders all branches of order 3 and higher invisible and unselectable and can be undone with 'Edit > QSM > Show/Hide > Show all'.

Finally lets select one of the cylinders. This will display its descriptors in the QSM inspector (lower right corner) as well as the available functions in the toolbar (above the 3d view).

===== "Fixing" a diameter =====

{{ :tutorials:qsm:fit_diameter.gif?direct |}}

The buttons that appear in the node toolbar if a shoot is selected are representing the shoot based tools ( see: [[https://manual.grogra.de/de.grogra.qsm/ch04.html#shoot-based | online documentation]]). 
These tools are always applied on the selected shoots, lets first try a simple one, that only requires one selection: "average a diameter".

First find a shoot that has a significant (and probably unrealistic) diameter difference to its parent and successor. Select this shoot and the fit diameter button:
{{: tutorials:qsm:fitdiameter.png?direct&18|}}.

This sets the diameter of the shoot to the average of the parent and the child diameter. 
===== Smoothing =====

{{:tutorials:qsm:smooth_and_cut.gif?direct |}}

Some tools require more than one input, for example the smoothing function which replaces a path of cylinders with one cylinder straight from the first selected one to the second selected one. 

This can be used to improve reconstruction issues(such as wrongly rotated cylinders, or wired curves), by first selecting a shoot below the "issue", then pressing the `ctrl key` and while still holding the key selecting the shoot above the issue and release the `ctrl key`.  Now press the smooth button: {{:tutorials:qsm:smooth.png?direct&18|}} 

(Please make sure both  shoots are from the same order! To do a similar step with different orders please consider the bridge tool.)

To improve the result a bit we can simply apply the Split tool: {{:tutorials:qsm:slice.png?direct&18|}} on the new cylinder and cut it in half. Finally we might also adjust the diameter again to give it a more conical appearance. 


===== Readjusting taxonomy =====

In a QSM as a structured dataset, each shoot hold the information about its direct parent, which influences metrics such as the branching order or the trend. In GroIMP this relationship is displayed in the project graph. 
Using the GUI tools it is possible to change this relationships without effecting the geometrical position of the branches. 

==== Adjusting lateral branching ====


{{ :tutorials:qsm:rearange_lateral.gif?direct|}}

If a branch seems to be connected to the wrong parent, (e.g. two shoots emerge in close proximity on the trunk and one is wrongly considered as a lateral child of the other) this can be corrected using the "link as lateral child" tool. 
To do so first select the new parent, hold 'ctrl-key', select the child shoot and press the "link as lateral child" button: {{:tutorials:qsm:latchild.png?direct&18|}}

==== Adjust apical branching ====

{{ :tutorials:qsm:rearange_apical.gif?direct|}}

The other main source of taxonomical error is that the reconstruction algorithm choose the wrong child to the the apical successor. This can be fixed with the "link as apical child" tool, by changing the type of connection or creating new once. 

It is important to ensure that no shoot end up having two successor! While this is possible for GroIMP, it is not working well with the qsm plugin since it does not follow the logic of the taxonomy.


For example if we want to change the apical shoot as shown in the gif above, we first turn the old apical child into a lateral one by selecting first the parent, then the child as explained above.
Afterwards we can follow the same steps with the parent shoot and the new apical shoot but press the "link as apical child" button: {{:tutorials:qsm:apicalchild.png?direct&18|}}      
  


===== Shift to parent =====

{{ :tutorials:qsm:shift_parent.gif?direct|}}

Either based on the reconstruction process or the previous changes, QSMs are likely to have gaps between the parent and the child shoot. The GroIMP QSM plugin provides a simple shifting approach to move a shoot closer to its parent.

As shown in the gif,this can be applied in different configurations:

{{:tutorials:qsm:jumpend.png?direct&18|}} : move child to the end of the parent shoot.

{{:tutorials:qsm:jumpaxis.png?direct&18|}} : move child to the closest point on the axis of the parent shoot.

{{:tutorials:qsm:jumpstart.png?direct&18|}} : move child to the start of the parent shoot.

{{:tutorials:qsm:jumpmiddel.png?direct&18|}} : move child to the middle of the parent shoot.



==== Tree wide ====

{{:tutorials:qsm:shift_all.gif?direct|}}

All four of this approaches can also be applied tree wide (on all shoots at the same time). 
This should be done with caution because it can change the shape of the data quite intensely. 

The function can be found in the main menu 'Edit > QSM > shift all > ...', in the example in the gif the fit to axis version is used.

===== Export =====

{{:tutorials:qsm:export.gif?direct|}}


To export the processed QSM for further usage, the export function in the menu of the 3d view is used: 'View > Export > complete scene'. 
This allows to export to a qsm file that can be processed using e.g. the [[https://github.com/aidanmorales/rTwig | rtwig]] library.  Moreover it would also be possible to export to a range of other formats supported by GroIMP.