.. include:: ../macros.hrst .. include:: ../abbreviations.hrst .. _chapter:Selections: Selections ########## Selecting blocks in a model is important for the function of many filters, but in order to successfully work with them, it is important to know two three things about them in the context of |ATGV| and |ParaView|. With this it makes sense to dedicate an entire chapter of this manual only to selections. .. index:: Selection Fundamentals .. _sec:FundamentalsAboutSelections: Fundamentals about Selections in |ATGV| ======================================= The selection system of |ATGV| is inherited from |ParaView|, but |ATGV| has to use it in a slightly uncommon way for some of it's filters. Some basics that need to be known: - Within the entire **filter pipeline**, always **only one selection** can exist. This is important to know because many filters do rely on an active selection, and it is of course possible to have more than one filter in the pipeline that needs a selection as input. - The filter pipeline can be saved into a **state file** (***.pvsm** file), but this does not include the active selection. However, the selection definition is retained as a **property**, so it will be recovered if a state file is loaded. .. index:: Extract Selection filter The effect of the latter is that a pipeline with several filters that require selections will work properly and can even be saved to and loaded from **state files**, as illustrated in :numref:`fig:ExtractSel1` to :numref:`fig:ExtractSel3`. A problem arises if the user wants to go back in the pipeline and **modify** a selection. .. figure:: ../images/extract_sel_01.png :name: fig:ExtractSel1 :width: 40% :align: center A **demo model** with some **selected blocks**. .. figure:: ../images/extract_sel_02.png :name: fig:ExtractSel2 :width: 40% :align: center An **Extract Selection** filter was appended to the filter pipeline and the extracted blocks were extracted. .. figure:: ../images/extract_sel_03.png :name: fig:ExtractSel3 :width: 80% :align: center The pipeline with **demo model** and **Extract Selection** filter was saved to a **state file** and loaded back into |ATGV|: The render view shows the extracted blocks like after initially applying the filter. The **"trick"** that |ATGV| and |ParaView| applies to achieve the result as in :numref:`fig:ExtractSel3` can be seen in the **Properties** panel: parameters of the selection were saved and recovered as properties of the filter. However, going back in the pipeline, the selection does not reappear: it does not exist any more. What the user can do: - Go back to the block model, - Make a completely new selection, - In the properties panel of the filter, press the :guilabel:`Copy Active Selection` button and - Press also the :guilabel:`Apply` button. As a result, the displayed **selection parameters** will appear in the **Properties** panel, and a new extraction is shown in the view. .. admonition:: **Did you know?** :class: tip The example shows the **typical order** of actions with selections that require a selection: 1) Do some **selection** on the pipeline item that **precedes** the pipeline item that represents the filter. 2) Add the **filter** that will recognize the existing selection and show it's parameters in the **Properties** panel. 3) If the user wants to **change** the selection now, he needs to switch between **input item** and **filter item** in the pipeline browser accordingly. .. index:: Selection Tools Selection Tools =============== Most of the selection tool buttons are found immediately above the **Render View** (3D view) panels. .. admonition:: **Did you know?** :class: tip **In the following sections, only selection tools for cells will be explained!** The **Athos Render View** in |ATGV| is a special version of the **Render View** that exists already in |ParaView|. The difference is the availability of **selection tool buttons**. Functionality is not added, but removed: The original render view has the same selection tools not only for **cells**, but also for **points**. Why has this functionality been removed for |ATGV|? It is because we have a very strong focus on **block models**, and in this special case the availability of point selection buttons is only confusing! This is not a problem, because for all cases where the user needs point selection tools, the original **Render View** is still available. Select Cells On |selectcellson| ------------------------------- .. |selectcellson| image:: ../images/pqSurfaceSelectionCell.png Select a rectangle and all model blocks (cells) that are visibly partially or fully inside this rectangle will be selected. An example of this functionality is shown in :numref:`fig:SelectCellsOnExample`. .. figure:: ../images/selectcellsonexample.png :name: fig:SelectCellsOnExample :width: 80% :align: center With the **Select Cells On** |selectcellson| function, only visible surface blocks are selected within a rectangular view area. Select Cells Through |selectcellsthrough| ----------------------------------------- .. |selectcellsthrough| image:: ../images/pqFrustumSelectionCell.png Same as above, but in this case also all those model blocks (cells) will be selected that are visibly and invisibly inside a rectangular prism, as seen in :numref:`fig:SelectCellsThroughExample`. .. figure:: ../images/selectcellsthroughexample.png :name: fig:SelectCellsThroughExample :width: 80% :align: center The difference between **Select Cells Through** |selectcellsthrough| and **Select Cells On** |selectcellson| is the fact that the first will select only those model blocks that are invisibly "behind" the visible selected rectangle. .. admonition:: **Hint** :class: tip The **Select Cells Through** tool can be pretty dangerous because it will select blocks that you do not even see because they are behind the visible surface blocks! There are two things that you can do to ensure best possible control of what is going on: - In the **View** panel, check the **Camera Parallel Projection** option to gain more control about which model blocks will actually be affected. - The **Set View Direction to...** buttons in the **toolbar** can be used to to align the view exactly in parallel to one of the main coordinate axes. Select Cells with Polygon |selectcellspolygon| ---------------------------------------------- .. |selectcellspolygon| image:: ../images/pqPolygonSelectSurfaceCell.png This tool allows to select blocks inside a more complex area than a simple rectangle. It selects only blocks at the visible surface, as shown in :numref:`fig:SelectCellsPolygonExample`. .. figure:: ../images/selectcellspolygonexample.png :name: fig:SelectCellsPolygonExample :width: 80% :align: center In order to select surface blocks with the **Select Cells with Polygon** tool, press the left mouse button, move along the desired outline, and once the button is released, the polygon will be closed automatically. Select Cells Interactive |selectcellsinteractive| ------------------------------------------------- .. |selectcellsinteractive| image:: ../images/pqSurfaceSelectionCellInteractive.png The **Select Cells Interactive** tool is a **toggle** that is turned on or off by pressing the |selectcellsinteractive| button. If it is on, clicking on a model block will select it. .. admonition:: **Hint** :class: tip **Make sure to always turn this tool off after use!** There is no automatism that would turn the tool off automatically at any time. If it is not done manually, the behaviour of the view will be "strange", and in the worst case unintended things will happen. .. index:: Find Data tool .. index:: Selection by criteria Find Data |finddataicon| ------------------------ .. |finddataicon| image:: ../images/pqFindData.png The **Find Data** docking panel is certainly the most powerful selection function: It selects model blocks (*cells*) by criteria. The icon |finddataicon| cannot be found among the other selection tool buttons but in the main **toolbar** of |ATGV|. Alternatively, the Find Data docking panel can also be opened through the **View** menu, and it will appear as shown in :numref:`fig:FindDataDock`. .. figure:: ../images/finddatadock.png :name: fig:FindDataDock :width: 80% :align: center The **Find Data** docking panel allows to specify criteria for the selection of model blocks .. admonition:: **Note** :class: tip The **Find Data** tool is very powerful regarding selections by attributes, but it handles only **numeric** attributes, not **strings**, as shown in :numref:`fig:FindDataExample`. .. figure:: ../images/finddataexample.png :name: fig:FindDataExample :width: 80% :align: center In this example, **Find Data** is supposed to select blocks in the ``Lower Limestone`` geological unit. In the **N_Unit** attribute, these appear as ``Lower Lst``, and in the 3D display they can be shown as such in the **legend**. However, **Find Data** can only handle **numeric** attributes, so another attribute had to be introduced, **Geology**, where the same units are represented by code numbers - ``3`` in this case. Add, Subtract or Toggle Selection ================================= By default, selection tools will always **replace** an existing selection. This behaviour can be changed by activating one of the following selection mode buttons at the top of a **Render View** panel: **Add Selection** |addselection| If this selection mode is turned on, any new selection will be **added** to the already existing selection. **Subtract Selection** |subtractselection| With this selection mode, all selection tools will actually **unselect** blocks. **Toggle Selection** |toggleselection| In this mode, selection tools will work as a **toggle**: selected blocks will be unselected and unselected blocks will be selected. .. |addselection| image:: ../images/pqSelectPlus.png .. |subtractselection| image:: ../images/pqSelectMinus.png .. |toggleselection| image:: ../images/pqSelectToggle.png Grow and Shrink Selections ========================== Two more handy functions, with tool buttons directly at the top of the **Render View** panels: **Grow Selection** |growselection| Pressing this button will try to **add** one more model block to the existing selection in all possible directions. **Shrink Selection** |shrinkselection| This function will do the inverse of the previous function and try to **remove** model blocks from the border of the current selection. **Note** however, that it will work only with model blocks that were previously added by the **Grow Selection** function! .. |growselection| image:: ../images/pqPlus.png .. |shrinkselection| image:: ../images/pqMinus.png .. index:: Selections for Attribute Manipulation .. index:: Calculator for Selection filter .. index:: Write Value filter .. index:: Write Multi Values filter .. _sec:SelectionsAttributeManipulation: Selections for Attribute Manipulation ===================================== The |ATGV| software extends |ParaView| with some simple **selective attribute manipulation functions**. A problem is the fact that the |ParaView| selection system as described in :numref:`sec:FundamentalsAboutSelections` is not really made for such kind of functionality. As a consequence, these specific |ATGV| plugins for selective attribute manipulation are dealing with selections in a somewhat different way than other plugins are doing. Specifically, these explanations are about the following plugins: - :ref:`sec:CalcForSelection` - :ref:`sec:WriteValue` - :ref:`sec:WriteMultiValues` For the user, the most important difference is the order of activation: - **Common** 1) **Select** blocks 2) Activate the **filter** - **Selective Attribute Manipulation** 1) Activate the **filter** 2) **Select** blocks The important point is, that, other than described in :numref:`sec:FundamentalsAboutSelections`, selections should be recovered as far as possible if the user goes back in the **Pipeline Browser** in order to **change a selection**. With the common setup, this works only as long as there is not more than one selection in the entire pipeline and if it is not re-loaded from a state file. The series of screenshots from :numref:`fig:SelectManipulateExample1` to :numref:`fig:SelectManipulateExample4` will explain the point with an example, where first 3 values were defined in the block model using 3 instances of the **Write Value** filter, then the selection for the first of these filters was changed. .. figure:: ../images/selectmanipulateexample1.png :name: fig:SelectManipulateExample1 :width: 80% :align: center A new attribute **NewAtt** was created in this block model and 3 different values were assigned with 3 instances of the **Write Value** filter. .. figure:: ../images/selectmanipulateexample2.png :name: fig:SelectManipulateExample2 :width: 80% :align: center **First** turn off the display of **WriteValue3**, in order to hide also the **selection** that is related to it. **Then** turn on **WriteValue1** by clicking on the **eye** symbol. With this, the **selection** that was related to this filter will be restored. .. figure:: ../images/selectmanipulateexample3.png :name: fig:SelectManipulateExample3 :width: 80% :align: center After activating the **Add Selection** option in the toolbar above the view, an additional region was selected with the **Select Cells with Polygon** filter. Pressing :guilabel:`Apply` will extend the area with **NewAtt** value of 6. .. figure:: ../images/selectmanipulateexample4.png :name: fig:SelectManipulateExample4 :width: 80% :align: center Again **WriteValue1** should be unchecked first before showing **WriteValue3** again. .. admonition:: **Note** :class: tip The **order** of hiding and showing items in the pipeline can be important because of the rule that always **only one single selection** can really exist in the **entire pipeline**. If two pipeline items with selections are shown at the same time, the outcome may not always be predictable. .. admonition:: **Hint** :class: tip Please make use of the :guilabel:`Save` and :guilabel:`Load` buttons related to the **Selection IDs** in the **Properties** panel: If a complex selection should better not get lost accidentally, it should be saved to a file, so it can be easily restored without much effort. .. admonition:: **Did you know?** :class: tip Creating a new attribute and assigning 3 different values (plus a background value) as shown in :numref:`fig:SelectManipulateExample1` can also be achieved with only one instance of the **Write Multi Values** filter.