User Guide
==========

Overview
--------

The purpose of **Roll** is to build (*design*) surveys first, using a template based approach, with the help of design wizards.
Once completed, the survey layout can be checked visually in the *Layout* tab, before running some analysis jobs using 'worker threads'.
The template information can be converted into geometry tables, eliminating any source or receiver duplication caused by template overlap.
The plugin supports both template-driven survey analysis as well as geometry-driven analysis. 
The latter can be based on created geometry tables, or imported SPS data.

At a high level, Roll lets you:

* Create or load a survey project;
* Define blocks, templates, seeds, patterns, and roll along behavior;
* Generate geometry tables from the template definition;
* Run binning analysis from templates or geometry tables;
* Inspect analysis outputs inside Roll; and
* Export geometry and raster outputs to QGIS.

Prerequisites
-------------

Roll runs inside QGIS and expects its Python dependencies to be installed in the QGIS Python environment,
typically from the OSGeo4W shell on Windows. Roll has not yet been tested on Linux or MacOS,
but should work on those platforms as well, provided the dependencies are installed in the QGIS Python environment.

.. note::

   It is possible to run Roll independently from QGis. Obviously, interaction with QGis will then be disabled. A batch file has been created for this purpose.
   The batch file is included in the GitHub repository. For security reasons it is not uploaded to the OSGeo Plugins repository. The GitHub repository can be found `here <https://github.com/MrBeee/roll>`__.


Core Concepts
-------------

Roll uses a small set of domain concepts throughout the User Interface and file formats.

Block
   A survey consists of one or more rectangular blocks.

Template
   Each block contains one or more templates. A template describes how sources and receivers are arranged together before rolling.
   Sources and receivers are defined by seeds and grow lists. Each template requires at least one receiver seed and one source seed to create output traces.

   .. note::

      A template defines the combination of all receivers that are active for all
      sources *within the same template*. This means that a template with 10
      source points and 1,000 receivers will result in 10 x 1,000 = 10,000
      output traces.
  
      During processing part of these traces may be filtered out based on binning parameters, but the template definition itself does not have a concept of trace filtering. 

Seed
   A seed is the starting location of a source or receiver definition.

Grow list
   Each seed can be grown in different directions up to three times. These growth steps can therefore turn a point into a line, a line into a grid, and a grid into interwoven grids.

Roll list
   The seeds and their grow steps make up a single template. Each template can then be rolled in different directions repeating it across the survey area. 
   The roll steps (*maximum three*) are defined in a roll list that is owned by its block.

Template versus geometry
   Template-based processing uses a cookie cutter approach to keep the survey definition compact, whereby each cookie is rolled according to the roll list. 
   Templates are ideal for survey design and for processing that focuses on the survey layout, such as fold maps and offset maps.
   The downside of the template approach are twofold:

   1. Source and receiver locations are implicit and not directly editable. They are repeated many times in the survey design due to template overlap
   2. You can't easily represent complex survey layouts that don't fit the cookie cutter approach, such as surveys with a lot of local variation or with non-rectangular geometry.

   Geometry-based processing uses explicit source and receiver coordinates, whereby each source and receiver position is defined individually, avoiding any duplication.
   By running ``Create Geometry from Templates``, lists with unique source and receiver locations are generated as well as a relational file, that preserves which receivers are active for each shot. 
   
   Geometry-based processing is ideal for working with complex survey layouts and for processing that focuses on the actual source and receiver positions, such as trace-table views and spider plots.
   The source and receiver locations can be exported to QGIS, where they can be manipulated (*moved around, inactivated, or deleted*). 
   The edited source and receiver tables can be re-imported into Roll which is especially useful for QC of the edited source- /receiver points,
   This approach can alos be used for analysis of existing surveys that have been imported using SPS data.

Project files and outputs
-------------------------

Roll project files use the Extensible Markup Language (XML) format and the ``.roll`` file extension. XML is a widely used format for structured data, and has  several advantages:

* It is human-readable and can be edited with a text editor directly within Roll's XML pane, if necessary.
* It supports a hierarchical structure, which is very suitable for representing the nested nature of survey elements such as blocks, templates, seeds, and rolls.
* It allows for the inclusion of metadata, such as the coordinate reference system (CRS) in Well-Known Text (WKT) format, which is essential for geospatial applications.
* It is extensible, allowing for the addition of new elements and attributes as the software evolves, avoiding hassle with version management of project files

Apart from the project file, Roll also generates analysis outputs that are stored alongside the project as binary numpy files. 
These outputs include fold maps, offset maps, and other visualizations that are derived from the survey geometry and processing parameters. 
The "full-binning" methods use a memory-mapped analysis file so large trace tables can be worked with incrementally instead of being loaded fully into memory.

Below, the core of the XML structure is illustrated with a simplified example. The actual XML structure includes additional attributes and elements to capture the full range of survey design options and metadata.

.. code-block:: xml

   <block_list>
      <block>
         <name>Block-1</name>
         <borders>
           <src_border xmin="-20000.0" xmax="20000.0" ymin="-20000.0" ymax="20000.0"/>
           <rec_border xmin="0.0" xmax="0.0" ymin="0.0" ymax="0.0"/>
         </borders>
         <template_list>
            <template>
               <name>Template-1</name>
               <roll_list>
                  <translate n="10" dx="0.0" dy="200.0"/>
                  <translate n="10" dx="250.0" dy="0.0"/>
               </roll_list>
               <seed_list>
                  <seed x0="5975.0" src="True" y0="625.0" argb="#77ff0000" typno="0" azi="False" patno="0">
                     <name>Src-1</name>
                     <grow_list>
                        <translate n="1" dx="250.0" dy="0.0"/>
                        <translate n="4" dx="0.0" dy="50.0"/>
                     </grow_list>
                  </seed>
                  <seed x0="0.0" src="False" y0="0.0" argb="#7700b0f0" typno="0" azi="False" patno="1">
                     <name>Rec-1</name>
                     <grow_list>
                        <translate n="8" dx="0.0" dy="200.0"/>
                        <translate n="240" dx="50.0" dy="0.0"/>
                     </grow_list>
                  </seed>
              </seed_list>
            </template>
         </template_list>
      </block>
   </block_list>

Main Analysis Outputs
---------------------

Depending on the workflow and the chosen processing mode, Roll produces various analysis plots:

In the **Layout** tab these are

* Analysis area
* fold map
* minimum / maximum offsets
* rms offset increments
* Max offset gaps
* Illumination regularity map
* Spider plots for individual bins

The **layout** tab contains buttons to export these plots directly to QGis in a georeferenced manner. 
This funcionality is also available from the File -> export menu.

Under the **Analysis** tab, one can find:

* A trace table with all binning results
* Inline / crossline offsets
* Inline / crossline azimuths
* Inline / crossline stack response
* KxKy stack response
* Common Focal Point (CFP) analysis for a single point with:

  * In the spatial (x, y) domain:

    * Source beam
    * Receiver beam
    * Resolution function

  * In the Radon domain:

    * Source beam
    * Receiver beam
    * AVP function

* Offset histogram for the whole analysis area
* Offset / Azimuth diagram for the analysis area

'Full binning' extends the basic outputs with detailed per-trace information such
as line and stake numbers, source and receiver coordinates, CMP coordinates,
travel time, offset, azimuth, and unique-fold related values.


Survey Wizards
--------------

Roll provides separate wizards for **land** and **marine** survey design.

Land/OBN Survey Wizard
~~~~~~~~~~~~~~~~~~~~~~

The land/OBN survey wizard supports several geometry types:

1. orthogonal
2. parallel
3. slanted
4. brick
5. zigzag

Marine Survey Wizard
~~~~~~~~~~~~~~~~~~~~

The marine survey wizard is specialized in towed-streamer acquisition. It accounts
for turning-radius constraints and race-track style acquisition planning when
constructing practical survey layouts. 
It tries to optimize race track size to achieve minimal survey duration

Importing SPS Data
------------------

Legacy SPS data can be imported from the file menu and processed in much the
same way as internally generated geometry tables.

Roll ships with predefined SPS dialects and allows users to define and
store additional SPS dialects by adjusting columns used for line number, point
number, northing, and easting. This makes the plugin useful both for survey
design and for QC or re-analysis of existing acquisition data.

Editing Survey Files
--------------------

Roll helps users avoid direct XML editing in almost all cases.

1. New surveys can be created with the land or marine survey wizard.
2. Existing surveys can be modified in the property pane, which updates
   the XML structure behind the scenes.

.. note::

   Advanced users can still edit the XML directly and apply those changes using
   the ``Reload document`` action (Ctrl+F5 from the View menu).


Interaction with QGIS
---------------------

Generated geometry, imported SPS data, and raster analysis products can all be
exported to QGIS. In QGIS, source and receiver points can be moved, deleted, or
marked inactive and then loaded back into Roll for renewed analysis.

.. figure:: ../../images/foldmap.png
   :alt: Fold map of the Noordoostpolder example project

   Fold map of the Noordoostpolder example project.


3D View
-------

Roll includes a 3D view for a subset of the survey layout. This is especially
useful when using 'binning against a dipping plane' dipping-plane surveys,
or when using well trajectories, and VSP-style geometry.
Rolling templates are too expensive to render fully in 3D, so the view only allows 
non-rolling seeds and related geometry that are most useful to inspect.

.. figure:: ../../images/3D_vsp_image.png
   :alt: 3D representation of a survey area

   3D representation of a survey area.


Related Help
------------

For the detailed QGIS editing and round-trip workflow, use the dedicated
:doc:`Roll and QGIS Interface Guide <qgis-interface-guide>` page in the documentation.