# 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.

## 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.

    <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.

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.

3D representation of a survey area.

## Related Help

For the detailed QGIS editing and round-trip workflow, use the dedicated Roll and QGIS Interface Guide page in the documentation.