# User manual

## Database creation

OpenLog provides its own borehole data storage library called [xplordb](https://gitlab.com/geolandia/openlog/xplordb).  
`xplordb` meets [GeoSciML](https://www.ogc.org/standards/geosciml) standards and relies on `PostgreSQL/Postgis` or `spatialite` for its backend component.

<div style="padding:52.92% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/733919902?h=ec4d0bcd08&amp;badge=0&amp;autopause=0&amp;player_id=0&amp;app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen style="position:absolute;top:0;left:0;width:100%;height:100%;" title="How to set up a database in OpenLog"></iframe></div><script src="https://player.vimeo.com/api/player.js"></script>

### Spatialite - standalone

:::{warning}
`Spatialite` databases are ill suited to handle datasets > 150mB.  
They also lack both concurrent access capability and the notion of user privileges.
:::

To create a new `spatialite` database:

1. go to `OpenLog` -> `Database` -> `Create` -> `Spatialite database`

    ```{image} images/create_new_spatialite_01_menu.png
    :alt: create_new_xplordb_01_menu
    :class: bg-primary
    :width: 400px
    :align: center
    ```

2. Choose where to save the database file.

You are now connected to the `spatialite` database and ready to import data.

### PostgreSQL - xplordb

To create a new `xplordb` database and provided that you have access to an active PostgreSQL + Postgis server:

   1. go to `OpenLog` > `Database` -> `Create` -> `XplorDB database`

      ```{image} images/create_new_xplordb_01_menu.png
      :alt: create_new_xplordb_01_menu
      :class: bg-primary
      :width: 400px
      :align: center
      ```

   2. input the database `Host` IP/URL and `Port` number or refer to a `Service`

      ```{image} images/create_new_xplordb_02_connection.png
      :alt: create_new_xplordb_02_connection
      :class: bg-primary
      :width: 400px
      :align: center
      ```

      ```{Note}
        database creation is only available to PostgreSQL users with sufficient privileges
      ```

   3. review authentication parameters in the `Basic` tab
   4. verify authentication parameters by using the `Test connection` button then click `Next`
   5. input a database name and set remaining parameters as desired

      ```{image} images/create_new_xplordb_03_xplordb_parameters.png
      :alt: create_new_xplordb_03_xplordb_parameters
      :class: bg-primary
      :width: 400px
      :align: center
      ```

      ```{Note}
        the `admin` user is mandatory and should be an `xdb_admin`
      ```

   6. click `Finish`
   7. connect to the newly created database

## Database connection

```{Note}
OpenLog integrates to multiple 3rd party databases but it is more efficient to work with native `xplordb` or `spatialite` databases.
```

### To spatialite

1. go to `OpenLog` > `Database` > `Connect` > `Spatialite`
2. click `Open` and browse to the database file or pick a previous connection

### To PostgreSQL

1. go to `OpenLog` > `Database` > `Connect` > `Xplordb`
2. input the host and port details of the PostgreSQL backend database
3. input the `Xplordb` database name
4. go to the Basic tab and input the `Xplordb` `admin` credentials

### To Geotic (3rd party)

1. go to `OpenLog` > `Database` > `Connect` > `Geotic`
2. input the host and port details of the MSSQL backend database
3. input the `Geotic` database name
4. input the `Geotic` user login and password

## Importing data

Once connected to an `xplordb` or `spatialite` database you may import tabular data from csv files or attribute tables.

### Import tabular collar data

1. go to `OpenLog` > `Import` > `Tabular data` > `Import collar data`

   ```{image} images/import_collar_01_menu.png
   :alt: import_collar_01_menu
   :class: bg-primary
   :width: 500px
   :align: center
   ```

2. select or create the person and dataset for the import

   ```{image} images/import_data_02_person.png
   :alt: import_data_02_person
   :class: bg-primary
   :width: 400px
   :align: center
   ```

   Click `Next`

4. browse to a **collar** data source and parameterize the importer either manually or by loading an `Import profile`

   In the title section are the following parameters:
      - `Data source`: either the path to a csv file, or a reference to an attribute table
      - `Header`: the number of top lines to skip from the data source
      - `Encoding`: character encoding standard, default is [utf 8](https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-2/#G11165)
      - `CRS`: an EPSG reference to the Coordinate Reference System to be used
      - `DTM` (optional): a Digital Terrain Model from which to extract collar elevations
      - `Date format` (optional): a Date, Time, and Time zone parsing templater
      - `Current time` (read-only): an example of the expected data according to `Date format`
  
   In the `File Format` section are the following parameters:
      - `CSV (comma separated values)` or `Custom delimiters` (mandatory): define the delimiter characters and text qualifiers for the purpose of parsing the csv file into a structured table

   In the `Column definition` section is a table of 7 columns and 4 rows:
      - The `Column` row references the column titles
      - The `Map` row presents a drop-down list, the list is comprised of the colum titles found in the csv file according to the user-defined `File Format` rules 
      - The `Unit` row specifies the physical unit of measurement (only available when importing custom fields)
      - The `Type` row specifies the data type (only available when importing custom fields)
      - The `No data` row specifies a value to be treated as null at import (only available when importing custom fields)
      - The `HoleID` column maps unique collar identifiers
      - The `Easting` column maps effective collar x coordinates in metres
      - The `Northing` column maps effective collar y coordinates in metres
      - The `Elevation` column (optional) maps collar z coordinates in metres AMSL
      - The `EOH` column (optional) maps effective collar total drilled length in metres
      - The `Pld. East.` column maps planned collar x coordinates in metres
      - The `Pld. North.` column maps planned collar y coordinates in metres
      - The `Pld. EOH` column (optional) maps planned collar total drilled length in metres
      - The `Dip` column (optional) maps collar inclination in degrees
      - The `Azimuth` column (optional) maps collar orientation in degrees
      - The `Date` column (optional) maps an arbitrary date

   Extra columns may be added/removed by clicking the ![](icons/add.svg) icon or remove them with the ![](icons/remove.svg) icon.

   In the `Sample Data` section is a preview table where the `File Format` parsing rules are applied to the csv file

   In the `Imported data` section is a preview table where the `Column definition` mapping rules are applied to the parsed csv file. This represents how the data will be stored in the database.

      ```{image} images/import_collar_02_menu.png
   :alt: import_collar_02_menu
   :class: bg-primary
   :width: 600px
   :align: center
   ```

   Click `Next`

5. review the summary of what **is to be be** imported into the database and click `Finish`

### Import tabular survey data

1. go to `OpenLog` > `Import` > `Tabular data` > `Import survey data`

   ```{image} images/import_survey_01_menu.png
   :alt: import_survey_01_menu
   :class: bg-primary
   :width: 500px
   :align: center
   ```

2. select or create the person and dataset for the import

   ```{image} images/import_data_02_person.png
   :alt: import_data_02_person
   :class: bg-primary
   :width: 300px
   :align: center
   ```

   Click `Next`

3. browse to a **survey** data source and parameterize the importer either manually or by loading an `Import profile`

   In the `Import options` section are the following parameters:
      - `Invert Dips` checkbox, OpenLog assumes negative dips down convention, check this box for positive dips down convention
      - `Data source`: either the path to a csv file, or a reference to an attribute table
      - `Header`: the number of top lines to skip from the data source
      - `Encoding`: character encoding standard, default is [utf 8](https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-2/#G11165)      
  
   In the `File Format` section are the following parameters:
      - `CSV (comma separated values)` or `Custom delimiters` (mandatory): define the delimiter characters and text qualifiers for the purpose of parsing the csv file into a structured table

   In the `Column definition` section is a table of 5 columns and 4 rows:
      - The `Column` row references the column titles
      - The `Map` row presents a drop-down list, the list is comprised of the colum titles found in the csv file according to the user-defined `File Format` rules 
      - The `Unit` row specifies the physical unit of measurement
      - The `Type` row specifies the data type
      - The `HoleID` column maps unique collar identifiers
      - The `Dip` column maps survey inclination in decimal degrees from +90° to -90° with 0° defined has the horizontal plane
      - The `Azimuth` column maps survey direction in decimal degrees from +0° to +359° clockwise with 0° defined has the grid North  
      - The `Length` column maps survey drilled lengths in metres

   In the `Sample Data` section is a preview table where the `File Format` parsing rules are applied to the csv file

   In the `Imported data` section is a preview table where the `Column definition` mapping rules are applied to the parsed csv file. This represents how the data will be stored in the database.

   ```{image} images/import_data_05_survey.png
   :alt: import_data_05_survey
   :class: bg-primary
   :width: 600px
   :align: center
   ```

   Click `Next`

4. review the summary of what **is to be be** imported into the database and click `Finish`

### Import tabular downhole data

1. go to `OpenLog` > `Import` > `Tabular data` > `Import downhole data`

   ```{image} images/import_assay_01_menu.png
   :alt: import_assay_01_menu
   :class: bg-primary
   :width: 400px
   :align: center
   ```
2. select or create the person and dataset for the import

   ```{image} images/import_data_02_person.png
   :alt: import_data_02_person
   :class: bg-primary
   :width: 300px
   :align: center
   ```

3. Either pick an existing downhole data series from the `Available downhole data` drop down menu or create a new one under `Create downhole data`.  
    When chosing the latter, the following parameters are made available:
      - The `Variable` parameter refers to the new downhole data series name as defined by the user
      - the `Domain` parameter refers to the authorized input set of the new downhole data series, it offers the `depth` option for measurements taken along the hole path and the `time` option for measurements taken over time at a single set depth
      - The `Extent` parameters refers to the granularity of the input set, it offers the `discrete` option for point measurements and the `extended` option for interval measurements

   ```{image} images/import_data_02_assay.png
   :alt: import_data_02_assay
   :class: bg-primary
   :width: 400px
   :align: center
   ```

   click `Next`

4. browse to a **downhole data** data source and parameterize the importer either manually or by loading an `Import profile`

   In the title section are the following parameters:
      - `Data source`: either the path to a csv file, or a reference to an attribute table
      - `Header`: the number of top lines to skip from the data source
      - `Encoding`: character encoding standard, default is [utf 8](https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-2/#G11165)     
      - `Date format` (optional): a Date, Time, and Time zone parsing templater
      - `Current time` (read-only): an example of the expected data according to `Date format`lithological intervals expanded to fill the newly created gap to the median point
      - `File name` references the path the csv file

   In the `Import options` section are the following parameters:
      - `Gap resolution`: specifies how data gaps are handled, options are `accept`, `reject`, `forward`, `backward`, `nearest`
         - `accept`: entry is be imported as is
         - `reject`: entry is be ignored
         - `forward`: overlying entry is imported instead
         - `backward`: underlying entry is imported instead
         - `nearest`: the entry is split at the midpoint and filled with the overlying and underlying entries   
      - `Overlap resolution`: specifies how data overlaps are handled, options are `reject`, `forward`, `backward`, `nearest`. In all cases, overlaping areas are removed and treated as gaps.

   In the `File Format` section are the following parameters:
      - `CSV (comma separated values)` or `Custom delimiters` (mandatory): define the delimiter characters and text qualifiers for the purpose of parsing the csv file into a structured table

   In the `Column definition` section is a table of 2 to 3 columns and 5 to 6 rows:
      - The `Column` row references the column titles
      - The `Map` row presents a drop-down list, the list is comprised of the colum titles found in the csv file according to the user-defined `File Format` rules
      - The `Unit` row specifies the physical unit of measurement
      - The `Type` row specifies the data type, the available data types are `Nominal`, `Numerical`, `Datetime`, `Categorical`, `Imagery`, `Polar`, and `Spherical`

         ```{image} images/import_data_types.png
         :alt: import_data_types
         :class: bg-primary
         :width: 250px
         :align: center
         ```      

      - The `No data` row specifies a value to be treated as null at import.
      - The `Conflicts` row is only available when importing data into a predefined table. It specifies how input data should interact with pre-existing data, the available options are `Ignore` (retain database data), `Overwrite` (replace database data with input data), `Merge from DB` (replace database null entries with input data), `Merge to DB` (replace input data null entries with database entries then overwrite)

         ```{image} images/import_data_conflicts.png
         :alt: import_data_conflicts
         :class: bg-primary
         :width: 350px
         :align: center
         ```
      
      - The `HoleID` column maps unique collar identifiers
      - When working with a `discrete` input set, the `Depth` column maps measurement depths.
      - When working with a `extended` input set, the `From_m` column maps the top of each interval while the `To_m` column maps the bottom of each interval.

   Data columns may be added/removed by clicking the ![](icons/add.svg) icon or remove them with the ![](icons/remove.svg) icon.

 In the `Sample Data` section is a preview table where the `File Format` parsing rules are applied to the csv file

   In the `Imported data` section is a preview table where the `Column definition` mapping rules are applied to the parsed csv file. This represents how the data will be stored in the database.

   ```{image} images/import_data_03_assay.png
   :alt: import_data_03_assay
   :class: bg-primary
   :width: 400px
   :align: center
   ```

   click `Next`

5. verify the database table creation parameters, ensure that no blank characters are present in any `Database column` or `Table Name` entries

   ```{image} images/import_data_04_assay.png
   :alt: import_data_04_assay
   :class: bg-primary
   :width: 400px
   :align: center
   ```

   click `Next`

6. review the summary and click `Finish`

   ```{image} images/import_data_05_assay.png
   :alt: import_data_05_assay
   :class: bg-primary
   :width: 400px
   :align: center
   ```

#### Numerical data specifics

If you have added at least one column with the `Type` set to `Numerical`, the `Uncertainty` section will display a table of 2 to 5 columns (based on the number of values used to describe uncertainty) with a row per `Numerical` variable.

- The `Column` column maps to numerical data fields as defined in the `Column definition` section
- When working with `Range` uncertainty, the `Interval` column maps the width of an error bar, the underlying distribution is assumed symmetrical

   ```{image} images/import_data_uncertainty_1.png
   :alt: import_data_uncertainty_1
   :class: bg-primary
   :width: 250px
   :align: center
   ```   

- When working with `Boundary pair` uncertainty, the `Lower outer` and `Upper outer` columns map the highest and lowest values of an error bar.

   ```{image} images/import_data_uncertainty_2.png
   :alt: import_data_uncertainty_2
   :class: bg-primary
   :width: 400px
   :align: center
   ```     

- When working with `Boundary quad` uncertainty, the `Lower outer` and `Upper outer` columns map the highest and lowest values of the error bar component of a box plot while the `Lower inner` and `Upper inner` columns map the highest and lowest values of the box component of a box plot.

   ```{image} images/import_data_uncertainty_3.png
   :alt: import_data_uncertainty_3
   :class: bg-primary
   :width: 750px
   :align: center
   ```    

  
:::{note}
Detection limits are only available to OpenLog Premium subscribers.
:::

If you have added at least one column with the `Type` set to `Numerical`, the `Detection limits` section will display a table of 3 columns with a row per `Numerical` variable.

- The `Column` column maps to numerical data fields as defined in the `Column definition` section
- The `Lower limit` column maps to the lower detection threshold
- The `Upper limit` column maps to the upper detection threshold

   ```{image} images/import_data_limits.png
   :alt: import_data_limits
   :class: bg-primary
   :width: 250px
   :align: center
   ```   

#### Categorical data specifics

   If you have added at least one column with the `Type` set to `Categorical`, the `Categories` section will display a table of 3 columns and as many rows as the number there are `Categorical` variables:

   - The `Column` column maps all categorical data as defined in the `Column definition` section
   - The `Category` column maps to a dictionary of allowed values
   - The `Validation` column presents a drop-down list of three filter options: `append` will add any unrecognized category from the csv file to the dictionary and therefore import all entries; `restrict` will eliminate single entries with unrecognized categories; `remove` will eliminate entries with unrecognized categories and all entries associated to the same `HoleID`

   ```{image} images/import_data_categories.png
   :alt: import_data_categories
   :class: bg-primary
   :width: 250px
   :align: center
   ```

 #### Imagery specifics

   If you have added at least one column with the `Type` set to `Imagery`, the csv data must abide the following:
   - Entries must contain a file path to the image, either absolute or relative to the csv file
   - Images must be in on of the supported formats as described in the [QImage documentation](https://doc.qt.io/qt-6/qimage.html)

#### Polar data specifics

   If you have added at least one column with the `Type` set to `Polar`, the csv data must abide the following
   - Entries must be expressed in decimal degrees from +0° to +359° clockwise with 0° defined has the grid North 

#### Spherical data specifics

   If you have added at least one column with the `Type` set to `Spherical`, the `Spherical data definition` section will display a table of 5 columns
   - The `Column` column maps spherical data fields as defined in the `Column definition` section
   - The `Type` column presents a drop-down list with two options: `LINE` refers to a spherical vector that describes the orientation of a 1D object; `PLANE` refers to a spherical vector that describe the orientation of the dip vector of a 2D object
   - The `Dip` column maps vector inclination in decimal degrees from +0° to +90° with 0° defined has the horizontal plane
   - The `Azimuth` column maps vector direction in decimal degrees from +0° to +359° clockwise with 0° defined has the grid North  
   - The `Polarity` column, in the case of a `Type` set to `PLANE`, indicates the hemisphere that the unit normal vector to the plane is directed towards, with 0 defined as the upper and 1 as the lower

### Import profiles

:::{note}
The import profile manager is only available to OpenLog Premium subscribers.
:::

Import profiles hold import parameters and may be saved to JSON files or into an XplorDB database.

The `Import profile manager` provides an interface to:
  - interact with database-bound import profiles,
  - create new import profiles, 
  - load pre-existing import profiles from file
  - schedule automated imports

  To access the `Import profile manager`, go to `OpenLog` > `Data` > `Manage` > `Import profiles`

  ```{image} images/import_profiles_0.png
  :alt: import_profiles_access
  :width: 300px
  :align: center
  ```

#### Import profile management

The `Import profiles` section of the `Import profile manager` contains a table with 4 columns to which entries may be added, removed, or edited:
- The `Name` column lists unique string identifiers for each profile
- The `Type` column presents a drop-down list with three options: `collar`, `survey`, and `downhole data`
- The `DH data` column is only active when the `Type` column is set to `downhole data` and presents a drop-down list of all eligible data tables found in the database
- The `Profile` column links to the `Profile edition` wizard which functions as a regular tabular importer such as the one described in the [Import tabular collar data](#import-tabular-collar-data) section

   ```{image} images/import_profiles_1.png
      :alt: import_profiles
      :width: 600px
      :align: center
      ```

To add a new entry:
   1. click the ![](icons/add.svg) icon in the `Import profiles` section of the `Import profile manager`
   2. type a name for the import profile in the `Name` column
   3. select the appropriate import mode in the `Type` column and if set to `downhole data`, pick the relevant downhole data table from in the `DH data` column
   4. click the ![](icons/search.svg) icon in the `Profile` column
   5. parameterize the import, then click `Finish`
   6. click the ![](icons/save.svg) icon and respond to the confirmation prompt

To remove an entry:
   1. select the entry
   2. click the ![](icons/remove.svg) icon and respond to the confirmation prompt

To edit an entry:
   1. select the entry
   2. click the ![](icons/edit.svg) icon
   3. repeat steps 2 to 6 of the add new entry instruction set

#### Import automation

The `Import scheduler` section of the `Import profile manager` contains a table with 12 columns to which entries may be added, removed, or edited:
- The `Name` column lists unique string identifiers for each import job
- The `Profile` column presents a drop-down list with all eligible import profiles in the database
- The `Source` column defines the target directory to import files from
- The `Person` column presents a drop-down list with all eligible `Person`s in the database
- The `Dataset` column presents a drop-down list with all eligible `Dataset`s in the database
- The `Frequency` column 
- The `Logs` column defines the target file to save import logs to
- The `Created` column displays the creation time and date of the import job
- The `Last import` column displays the time and date of the last run for the import job
- The `Total imports` column numbers attempts made for the import job
- The `Failed imports` column numbers failed attempts made for the import job
- The `Status` column advises the state of the import job as `Active` or `Inactive`

   ```{image} images/import_automation_1.png
      :alt: import automation
      :class: bg-primary
      :width: 600px
      :align: center
      ```

To create an import job:
   1. click the ![](icons/add.svg) icon in the `Import scheduler` section of the `Import profile manager`
   2. type a name for the import job in the `Name` column
   3. select an import profile from the drop-down list in the `Profile name` column
   4. click the `Source` entry to browse to the desired import location, note that all eligible files in the directory will be imported
   5. select a person from the drop-down list in the `Person` column
   6. select a dataset from the drop-down list in the `Dataset` column
   7. set the import schedule in terms of `Base` unit and `Frequency` via the `Frequency` column

      ```{image} images/import_automation_2.png
      :alt: import schedule
      :class: bg-primary
      :width: 200px
      :align: center
      ```
   8. click the `Logs` entry to browse to the desired location to save the log files
   9. click either the ![](icons/save.svg) or ![](icons/cancel_edit.svg) icon and respond to the confirmation prompt

To schedule an import job:
   1. select an `Inactive` entry from the `Import scheduler` table and review its parameters
   2. click the  ![](icons/clock.svg) icon to initiate the scheduler, this will set the `Status` of the import job to `Active` 

To run an import job immediately:
   1. select an `Inactive` entry from the `Import scheduler` table and review its parameters
   2. click the  ![](icons/start.svg) icon to run the job

To delete an import job:
   1. select an `Inactive` entry from the `Import scheduler` table and review its parameters
   2. click the ![](icons/remove.svg) icon delete the import job from the database, be aware that this cannot be reverted

### Import self-contained files 

OpenLog supports a selection of files which contain collar, survey, and donwhole data all in one.

#### Import AGS files

1. go to `OpenLog` > `Import` > `Tabular data` > `Import collar data`

   ```{image} images/import_ags_01_menu.png
   :alt: import_collar_01_menu
   :class: bg-primary
   :width: 500px
   :align: center
   ```

2. select or create the person and dataset for the import

   ```{image} images/import_data_02_person.png
   :alt: import_data_02_person
   :class: bg-primary
   :width: 400px
   :align: center
   ```

   Click `Next`

3. browse to an AGS file

   ```{image} images/import_ags_02_menu.png
   :alt: import_data_02_person
   :class: bg-primary
   :width: 400px
   :align: center
   ```

   Click `Next`   

4. Proceed as per step 4 of the [Import tabular collar data](#import-tabular-collar-data) instruction set.

5. Proceed as per step 3 of the [Import tabular survey data](#import-tabular-survey-data) instruction set.

6. Proceed as per step 4 of the [Import tabular downhole data](#import-tabular-downhole-data) instruction set.

## Downhole data table management

Users may create or delete downhole data tables using the `Downhole data administration` window

:::{note}
Downhole data table management is only available to OpenLog Premium subscribers.
:::


:::{Warning}
Deletion of tables is permanent.
:::

### Creating tables

1. go to `OpenLog` > `Database management` > `Manage downhole data`

   ```{image} images/manage_data_01.png
   :alt: manage_data_01
   :class: bg-primary
   :width: 300px
   :align: center
   ```

   Information about existing tables is listed in the assays section:
      - The `Name` column indicates the display name of the table
      - The `Domain` column indicates the authorized input set of the table
      - The `Extent` column indicates the supported input set of the table
      - The `Rows` column indicates the number of entries in the table
      - The `Columns` column indicates the number of attributes in the table
      - The `Validate` column encapsulates interactable buttons to confirm changes made to a table
      - The `Cancel` column encapsulates interactable buttons to revert changes made to a table
      
   ```{image} images/manage_data_02.png
   :alt: manage_data_02
   :class: bg-primary
   :width: 450px
   :align: center
   ```
2. Click the ![](icons/add.svg) icon to add a new line in the Assays section, this will also populate the Columns section
3. Input a `Name`, and select a `Domain`/`Extent` for the new table
4. Define the particulars of the new table in the Columns section as per step 5 of the [Import tabular downhole data](#import-tabular-downhole-data) instruction set
5. Click the relevant cell in the `Validate` column of the Assays section
6. click `Close`

### Altering tables

1. go to `OpenLog` > `Database management` > `Manage downhole data`
2. Select the table to be altered in the Assays section, this will also populate the Columns and Content sections
3. Define the particulars of the new table in the Columns section as per step 5 of the [Import tabular downhole data](#import-tabular-downhole-data) instruction set
5. Click the relevant cell in the `Validate` column of the Assays section
6. click `Close`

### Deleting tables

1. go to `OpenLog` > `Database management` > `Manage downhole data`
2. Select the table to be removed in the Assays section, this will also populate the Columns and Content sections
3. Click the ![](icons/remove.svg) icon to remove the table and review the warning
4. click `Close`

## Collar management

### Adding collars

1. go to `OpenLog` > `Add collar`

   ```{image} images/add_collar_01_menu.png
   :alt: add_collar_01_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

2. select or create a `Person` and `Dataset`
3. in the `Collar settings` section, set the general parameters:

   - `Index prefix` prepends a string to each collar name
   - `Index base` defines the total digit count of collar numbers
   - `Index start` appends a collar number number to each collar name
   - `DTM` points to an existing raster layer that will be used to retrieve collar elevation

4. tick the `Grid mode` checkbox if required

#### Point & click mode

If the `Grid mode` box is left unchecked, the user is generate new collar via point and click action directly onto the canvas to add new collar entries into an editable table of 9 columns:

- An untitled column for rank
- The `HoleID` column displays unique collar identifiers generated as per the `Index prefix`, `Index base`, and `Index start` parameters
- The `Easting` column displays the X coordinates retrieved on click from the canvas in metres
- The `Northing` column displays the Y coordinates retrieved on click from the canvas in metres
- The `Elevation` column displays the Z coordinates retrieved on click from the `DTM` in metres, defaults to 0 is no elevation surface is present
- The `EOH` column (optional) displays an optional the total measured length of the drillhole
- The `Pld. East.` column (optional) displays planned collar x coordinates in metres
- The `Pld. North.` column (optional) displays planned collar y coordinates in metres
- The `Pld. EOH` column (optional) displays planned collar total drilled length in metres
- The `Dip` column (optional) displays collar inclination in degrees
- The `Azimuth` column (optional) displays collar orientation in degrees

   ```{image} images/add_collar_02_menu.png
   :alt: add_collar_02_menu
   :class: bg-primary
   :width: 400px
   :align: center
   ```

Click `OK` to validate the changes and push the new collars to the database.

#### Grid mode

If the `Grid mode` box is checked, the user is able to generate a grid of points of a chosen orientation and spacing through clik-and-drag action over the canvas. 

The relevant parameters are:

- `Number` and `Spacing` represent two alternative means of defining the cardinality of the grid, either through a `Columns` number vs `Rows` number or via `Horizontal` intervals vs `Vertical` intervals
- The `Azimuth` defines the orientation of the grid relative to the grid North

The points are added to the collar table automatically:


   ```{image} images/add_collar_03_menu.png
   :alt: add_collar_03_menu
   :class: bg-primary
   :width: 400px
   :align: center
   ```

Click `OK` to validate the changes and push the new collars to the database.

### Editing/removing collars

1. select any number of points from the `Collar` or `Planned collar` layer

2. go to `OpenLog` > `Edit collars`

   ```{image} images/edit_collar_01_menu.png
   :alt: edit_collar_01_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

<!-- 3. a restricted QGIS attribute table populated with raw `Collar` data will open in [edit mode](https://docs.qgis.org/3.34/en/docs/user_manual/working_with_vector/attribute_table.html#editing-attribute-values). -->

3. a table containing raw `Collar` data as described in the [Adding collars section](#adding-collars) will open with every field editable except for those under the `HoleID` column

   ```{image} images/edit_collar_02_table.png
   :alt: edit_collar_02_table
   :class: bg-primary
   :width: 700px
   :align: center
   ```

## Desurveying

OpenLog makes use of the minimum curvature interpolator for its desurveying calculations.

```{Note}
In order to avoid potentially lengthy processing times, OpenLog does not desurvey drillholes on import by default.
```

1. Select any number of collars from the collar layer
2. go to `OpenLog` > `Desurvey holes` or right click into the canvas and click `Desurvey holes`
  
   ```{image} images/desurvey_01_menu.png
   :alt: desurvey_01_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

3. the orthogonal projection of the drillhole traces derived from collar orientation and surveys will be added to the `PLanned trace` and `Effective trace` layers, respectively.

      ```{image} images/desurvey_02_results.png
      :alt: desurvey_02_results
      :class: bg-primary
      :width: 500px
      :align: center
      ```

## Survey creation/edition

OpenLog includes basic survey edition capabilities.

1. Select any number of collars from the collar layer
2. go to `OpenLog` > `Edit surveys` or right click into the canvas and click `Edit surveys`

   ```{image} images/survey_edit_01_menu.png
   :alt: survey_edit_01_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

3. select or create a `Person` and `Dataset`
4. in the case of multiple collar selections, a `Collars` drop-down list of their HoleIDs will appear where each may be selected individually

   ```{image} images/survey_edit_03_table.png
   :alt: survey_edit_03_table
   :class: bg-primary
   :width: 400px
   :align: center
   ```

5. based on the `Collars` selection, relevant existing survey entries will populate a 3 column tables in the `Survey` section under an `Effective` tab and a `Planned` tab. Note that the `Planned` table lists a single entry as it assumes that drillholes were designed straight.

   - The `Depth` column defines the drilled length at which the survey entry was measured
   - The `Dip` column maps survey inclination in decimal degrees from +90° to -90° with 0° defined has the horizontal plane
   - The `Azimuth` column maps survey direction in decimal degrees from +0° to +359° clockwise with 0° defined has the grid North  

   New survey entries may be added or deleted by clicking the ![](icons/add.svg) icon or the ![](icons/remove.svg) icon, respectively.

   ```{image} images/survey_edit_02_table.png
   :alt: survey_edit_02_table
   :class: bg-primary
   :width: 500px
   :align: center
   ```

6. click `OK` to push the changes to the database

## Striplog visualization

### Downhole data visualization

1. Select any number of collars from the collar layer
2. go to `OpenLog` > `Display depth data` > `Plots` or right click into the canvas and click `Display depth data` > `Plots`

   ```{image} images/depth_viz_01_menu.png
   :alt: depth_viz_01_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

3. click the `Add` ![](icons/add_assay.svg) icon in the newly displayed data visualization panel

   ```{image} images/depth_viz_02_menu.png
   :alt: depth_viz_02_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

4. select any number of available variable from the drop-down list and click `OK`

   ```{image} images/depth_viz_03_menu.png
   :alt: depth_viz_03_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

      A double-pronged `Selection tree` will then populate itself with the relevant collars and downhole data references on the left side of the panel.  
    
      - The `Downhole data` tree references downhole data series as selected at step 4, each downhole data series then encapsulates a list of collars as selected step 1.  
      - The `Collars` tree references collars as selected at step 1, each collar then encapsulates a list of downhole data series as selected at step 4.  
    
      Both trees map to the same data and serve only as alternate interaction pathways. 
            
   ```{image} images/depth_viz_04_tree.png
   :alt: depth_viz_04_tree
   :class: bg-primary
   :width: 250px
   :align: center
   ```
      On click action over an element of the tree populates a `Symbology parameters` table under the `Selection tree` with a:
      - `Parameter` column
      - `Value` column

   ```{image} images/depth_viz_18_symbology_params.png
   :alt: depth_viz_18_symbology_params
   :class: bg-primary
   :width: 250px
   :align: center   
   ```

5. to remove a variable from the selection tree, left-click the variable name in the selection tree then click the `Remove` icon.

   ```{image} images/depth_viz_11_tree.png
   :alt: depth_viz_04_tree
   :class: bg-primary
   :width: 250px
   :align: center
   ```

#### Controls

Global display parameter controls are lined up in the toolbar at the top of the `Display depth data` panel

```{image} images/depth_viz_10_menu.png
:alt: depth_viz_06_sort
:class: bg-primary
:width: 500px
:align: center
```

##### Static

Static controls effect single, non-dynamic actions.

###### Symbology propagation

Symbology parameterization for a given data series is applied selectively using the `Apply` button:

   ```{image} images/depth_viz_19_application.png
   :alt: depth_viz_19_application
   :class: bg-primary
   :width: 200px
   :align: center
   ```

- the `To all` option option propagates symbology to all drillholes
- the `To tree selection` option propagates symbology according to the selection tree state
- the `To QGIS selection` option propagates symbology according to the QGIS selection state of the `collar` layer

###### Sorting and rearranging

The Display depth data panel offers several order controls over the graphs via the top menu bar.

The Sorting options are:

- `Sort by collar` ![](icons/sort_collar.svg) rearranges the graphs per the order of their collar in the bottom tree
- `Sort by source` ![](icons/sort_assay.svg) rearranges the graphs per the order of their data series in the top tree
- `Sort by X` ![](icons/icon_x_major.svg) rearranges the graphs per their ascending x coordinate (Easting)
- `Sort by Y` ![](icons/icon_y_major.svg) rearranges the graphs per their ascending y coordinate (Northing)
- `Sort by azimuth` ![](icons/icon_azimuth.svg) rearranges the graphs relative to a direction
- `Transpose` ![](icons/flat_grid.svg) rearranges the graphs over a single row. In this configuration, the zoom level will be shared among all graphs

   ```{image} images/depth_viz_06_sort.png
   :alt: depth_viz_06_sort
   :class: bg-primary
   :width: 200px
   :align: center
   ```

:::{note}
The `Sort by azimuth` option is only available to OpenLog Premium subscribers.
:::   

Click-and-drag-action allows arbitrary rearrangement of graphs.   

###### Vertical reference

Depth to altitude rescaling controls are also available in the Display depth data panel.

   ```{image} images/depth_viz_12_rescaling.png
   :alt: depth_viz_06_sort
   :class: bg-primary
   :width: 150px
   :align: center
   ```
The rescaling options are made available via a combo switch-button/drop-down menu:

- The `Depth/Altitude` button ![](icons/icon_moutain.svg) toggles between drilled length display and AMSL altitude
- The `Planned` entry from the drop-down list takes the collar orientation data as reference for the drillhole geometry
- The `Effective` entry from the drop-down list takes the survey data as reference for the drillhole geometry

###### Tick marks

:::{note}
Tick marks are only available to OpenLog Premium subscribers.
:::

The `Depth ticks` button ![](icons/depth_ticks_icon.svg) toggles the display of Depth/Alitude tick marks over the drillhole traces in the map view.

   ```{image} images/tick_marks_01.png
   :alt: tick_marks_01
   :class: bg-primary
   :width: 600px
   :align: center
   ```

Tick intervals are defined in the box immedialety next to it.

   ```{image} images/depth_viz_17_ticks.png
   :alt: depth_viz_17_ticks
   :class: bg-primary
   :width: 100px
   :align: center
   ```   

###### Viewer state retention

The `Viewer state` button ![](icons/icon_save_symbology.svg) summons a drop-down list with the following options:

   ```{image} images/depth_viz_14_symbol.png
   :alt: depth_viz_05_numerical
   :class: bg-primary
   :width: 150px
   :align: center
   ```

- The `Load` entry imports a full plugin state parameter configuration from a .json file
- The `Save As` a saves full plugin state parameter configuration to a human-readable .json file

##### Contextual

The standard PyQtGraph contextual menu is accessible via right click action into the display area.

   ```{image} images/depth_viz_07_numerical_symbology_8.png
   :alt: depth_viz_07_numerical_symbology_8
   :class: bg-primary
   :width: 300px
   :align: center
   ```

- The `View All` entry resets the axes to span the full extent of the data
- The `X-axis` and `Y-axis` entries are used to define the numerical extent of the graph either manually, as an upper/lower boundary pair, or automatically, as a percentage.
- The `Export` entry offers access the following file export options: `CSV` and `Image`


##### Interactive

Interactive controls are accessible by hovering the cursor over the display area:

- Scroll is controlled via Left click drag action or Ctrl+M3 wheel action
- Zoom is controlled via M3 wheel action

##### Hybrid

Hybrid tools are accessed through the main menu bar and controlled contextually or interactively.

The `Inspector Line` ![](icons/inspector_line.svg) toggles a data inspection line to be used over graphs which displays relevant information into a floating label overlay 

   ```{image} images/depth_viz_13_inspector_2.png
   :alt: depth_viz_13_inspector_2
   :class: bg-primary
   :width: 400px
   :align: center
   ```

Two options are available in a drop-down menu:
   ```{image} images/depth_viz_13_inspector_1.png
   :alt: depth_viz_13_inspector_1
   :class: bg-primary
   :width: 150px
   :align: center
   ```

- the `Synchronize` entry syncs the alignment of all lines which then behave as a single cross-graph line
- the `Projects on canvas` entry displays the overlay ontop of drillhole traces in the canvas.

   ```{image} images/depth_viz_13_inspector_3.png
   :alt: depth_viz_13_inspector_3
   :class: bg-primary
   :width: 350px
   :align: center
   ```

:::{note}
The `Projects on canvas` feature is only available to OpenLog Premium subscribers.
:::

#### Discrete numerical data

In the case of discrete numerical data, a series of line graphs display to the right side of the visualization panel.

   ```{image} images/depth_viz_05_numerical.png
   :alt: depth_viz_05_numerical
   :class: bg-primary
   :width: 750px
   :align: center
   ```

##### Symbology parameters

The `Symbology parameters` section for discrete numerical data lists the following:

- The `[NAME] (Unit)` category toggles the rendering of the graph and provides access to all other parameters. Its wording is as recorded in the database.
   - The `Bar chart/Line chart` button ![](icons/histogram.svg) toggles the graph display between a triangulated line chart and a median point centered bar chart.
   - The `Plot options` category groups parameters that control graph-wide elements:
      - The `Collar name` entry toggles the relevant text display at the top of the graph
      - The `Assay name` entry toggles the relevant text display of at the top of the graph
      - The `Column name` entry toggles the relevant text display of at the top of the graph
      - The `Log` entry toggles the x axis to a decimal log scale
      - The `X grid` and `Y grid` entries toggle the display of a regular grid over the plot space for the X and Y axes, respectively
      - The `Minimap` entry toggles the display of a miniature version of the graph for the purposes of navigation and scale awareness

         ```{image} images/depth_viz_07_numerical_symbology_9.png
         :alt: depth_viz_07_numerical_symbology_4
         :class: bg-primary
         :width: 300px
         :align: center
         ```
   - The `Style` subcategory provides a `Save` and `Load` function for the symbology profile to/from either the database of a .json file.

###### Line chart mode

- The `Line` category encompasses all symbology parameters related to the styling of the line:
  - The `Color` parameter sets the HSV, RGB, or HTML tone values of the line

   ```{image} images/depth_viz_07_numerical_symbology_5.png
   :alt: depth_viz_07_numerical_symbology_5
   :class: bg-primary
   :width: 200px
   :align: center
   ```
  
  - The `Width` parameter sets the thickness of the line
  - The `Style` parameter sets the pattern of the line, the available options are: `CustomDashLine`, `DashDotDotLine`, `DashDotLine`, `DashLine`, `DotLine`, `NoPen`, and `SolidLine`
  
   ```{image} images/depth_viz_07_numerical_symbology_6.png
   :alt: depth_viz_07_numerical_symbology_6
   :class: bg-primary
   :width: 200px
   :align: center
   ```

  - The `Cap Style` parameter sets the shape of the ends of the segments as defined by the `Style` parameter, the available options are: `Flat`, `Round`, and `Square`
  - The `Uncertainty` parameter toggles the display of error bars or box plots

   ```{image} images/depth_viz_07_numerical_symbology_1.png
   :alt: depth_viz_07_numerical_symbology_1
   :class: bg-primary
   :width: 300px
   :align: center
   ```
   
  - The `Detection limit` parameter toggles the display of detection limits in the form of greyed-out (outside of the limits) areas in the background of the graph
  
   ```{image} images/depth_viz_07_numerical_symbology_10.png
   :alt: depth_viz_07_numerical_symbology_10
   :class: bg-primary
   :width: 300px
   :align: center
   ```

   :::{note}
   The `Detection limit` feature is only available to OpenLog Premium subscribers.
   :::

- The `Point` category encompasses all symbology parameters related to the styling of the data points:
  - The `Symbol` parameter sets the shape of the point, the available options are: `None`, `Circle`, `Square`, `Cross`, and `Dot`

   ```{image} images/depth_viz_07_numerical_symbology_7.png
   :alt: depth_viz_07_numerical_symbology_7
   :class: bg-primary
   :width: 200px
   :align: center
   ```

  - The `Size` parameter sets the diameter of the points
  
   ```{image} images/depth_viz_07_numerical_symbology_3.png
   :alt: depth_viz_07_numerical_symbology_3
   :class: bg-primary
   :width: 300px
   :align: center
   ```

  - The `Color` parameter sets the HSV or RGB values of the points

   ```{image} images/depth_viz_07_numerical_symbology_5.png
   :alt: depth_viz_07_numerical_symbology_5
   :class: bg-primary
   :width: 200px
   :align: center
   ```

- The `Line shading` category encompasses all symbology parameters related to value-dependent color styling of the line:
  - The `Variable` entry provides a list of eligible variables to choose from the downhole data table
  - The `Classifier` entry set the statistical rules for placing the `Breaks` and interpolating over the `Palette`, the options are `Linear`, `Equal`, and `Quantile`
  - The `Palette` entry provides a list of color ramps to choose from
  - The `Breaks` parameter set the number of color references used to interpolate over the `Palette`  
  - The `Min` parameter sets the lowest value to be mapped to the color ramp
  - The `Max` parameter sets the highest value tto be mapped to the color ramp
  - The `Legend` parameter toggles an on-graph legend for the shading

   ```{image} images/depth_viz_07_numerical_symbology_4.png
   :alt: depth_viz_07_numerical_symbology_4
   :class: bg-primary
   :width: 300px
   :align: center
   ```

- The `Area shading` category encompasses all symbology parameters related to value-dependent color styling of the area between the line and the vertical axis:
  - The `Variable` entry provides a list of eligible variables to choose from the downhole data table
  - The `Classifier` entry set the statistical rules for placing the `Breaks` and interpolating over the `Palette`, the options are `Linear`, `Equal`, and `Quantile`  
  - The `Palette` entry provides a list of color ramps to choose from
  - The `Breaks` parameter set the number of color references used to interpolate over the `Palette`      
  - The `Min` parameter sets the lowest value to be mapped to the color ramp
  - The `Max` parameter sets the highest value tto be mapped to the color ramp    
  - The `Legend` parameter toggles an on-graph legend for the shading    

   ```{image} images/depth_viz_07_numerical_symbology_11.png
   :alt: depth_viz_07_numerical_symbology_11
   :class: bg-primary
   :width: 300px
   :align: center
   ```  

   The `Breaks` table may be accessed vby clicking the ![](icons/openlog_icon_area_shading.svg) icon.

   ```{image} images/depth_viz_07_numerical_symbology_12.png
   :alt: depth_viz_07_numerical_symbology_12
   :class: bg-primary
   :width: 250px
   :align: center
   ```  

###### Bar chart mode

- The `Bar pen` category encompasses all symbology parameters related to bar chart elements
  - The `Color` parameter sets the HSV or RGB values of bar outlines

   ```{image} images/depth_viz_07_numerical_symbology_5.png
   :alt: depth_viz_07_numerical_symbology_5
   :class: bg-primary
   :width: 200px
   :align: center
   ```

  - The `Width` parameter sets the thickness of bar outlines
  - The `Style` parameter sets the pattern of bar outlines, the available options are: `CustomDashLine`, `DashDotDotLine`, `DashDotLine`, `DashLine`, `DotLine`, and `SolidLine`
- The `Bar shading` category encompasses all symbology parameters related to value-dependent color styling of the bars:
  - The `Variable` entry provides a list of eligible variables to choose from the downhole data table
  - The `Classifier` entry set the statistical rules for placing the `Breaks` and interpolating over the `Palette`, the options are `Linear`, `Equal`, and `Quantile`  
  - The `Palette` entry provides a list of color ramps to choose from
  - The `Breaks` parameter set the number of color references used to interpolate over the `Palette`      
  - The `Min` parameter sets the lowest value to be mapped to the color ramp
  - The `Max` parameter sets the highest value tto be mapped to the color ramp    
  - The `Legend` parameter toggles an on-graph legend for the shading
  - The `Aggregate` parameter toggles an arithmetic mean data binning view when the `Classifier` is set to either `Equal` or `Quantile`

   ```{image} images/depth_viz_07_numerical_symbology_13.png
   :alt: depth_viz_07_numerical_symbology_13
   :class: bg-primary
   :width: 500px
   :align: center
   ```

#### Discrete categorical data

Unsupported.

#### Discrete imagery data

Unsupported.

#### Discrete polar data

   :::{note}
   The `Discrete polar data` feature is only available to OpenLog Premium subscribers.
   :::

In the case of discrete polar data, a series of [lineation markers](https://ngmdb.usgs.gov/fgdc_gds/geolsymstd/fgdc-geolsym-sec09.pdf) display to the right side of the visualization panel.

   ```{image} images/depth_viz_16_polar.png
   :alt: depth_viz_15_spherical
   :class: bg-primary
   :width: 400px
   :align: center
   ```

##### Polar symbology

- The `Markers` entry toogles the display of the lineation symbols
   - The `Size` parameter sets the scale of the symbols
- The `Rose diagrams` category toggles the display of, and groups parameters relative to circular bar chart representation of polar data:
  - The `Values` parameter toggles between the `dip` and `azimuth` angles to plot
  - The `N class` parameter set the number of bars in the diagram
  - The `Normalization` parameter toggles between bar-length and bar-area normalization methods
  - The `Intervals` button opens the `Depth intervals definition` window where: 
    - The `Number of intervals` parameter clusters measurements based on equal length intervals over the total depth of the drillhole
    - When the `Manual edit` checkbox is active, an `Intervals edition` editable table of 2 to 4 columns is made available :
      - The `From` column sets the upper boundary of an interval
      - The `To` column sets the lower boundary of an interval
      - The `Select from plot` allows the user to define interval upper and lower boundary via click-and-drag action directly over the `Markers` plot, available only when a single drillhole is selected
      - The `Select from table` allows the user to define interval upper and lower boundary via line selection over the relevant `Assay` attribute table, available only when a single drillhole is selected from the `Selection tree`
    - The `Propagation policy` parameter toggles between, available only when a downhole variable is selected from the `Selection tree`
     ```{image} images/depth_viz_15_spherical_2.png
      :alt: depth_viz_15_spherical_2
      :class: bg-primary
      :width: 300px
      :align: center
      ```
  
  - The `Color` parameter sets the HSV or RGB values of bar areas
  - The `Color ramp` subcategory encompasses all symbology parameters related to frequency-dependent color styling of the chart:
    - The `Name` entry provides a list of color ramps to choose from
    - The `Min count` parameter sets the lowest frequency count to be mapped to the color ramp
    - The `Max count` parameter sets the highest frequency count to be mapped to the color ramp
    - The `Common scale` entry applies rescale the `Min count` and `Max count` parameters to include all values accross intervals 
  - The `Grid entry` toggles the display of circular and radial graduation    
- The `Stereonets` category toggles the display of, and groups parameters relative to the stereographic projection of polar data:
  - The `Lines` subcategory encompasses all symbology parameters related to the styling of points
    - The `Symbol` parameter sets the shape of the point, the available options are: `None`, `Circle`, `Square`, `Cross`, and `Dot`
    - The `Size` parameter sets the diameter of the points
    - The `Color` parameter sets the HSV or RGB values of the points
  - The `Planes` subcategory encompasses all symbology parameters related to the styling of curves
    - The `Color` parameter sets the HSV, RGB, or HTML tone values of the line
    - The `Linewidth` parameter sets the thickness of the line
    - The `Symbol` parameter sets the pattern of the line, the available options are: `CustomDashLine`, `DashDotDotLine`, `DashDotLine`, `DashLine`, `DotLine`, and  `SolidLine`
   - The `Grid entry` toggles the display of conformal graduations
  - The `Intervals` button     
- The `Plot options` category groups parameters that control graph-wide elements:
  - The `Collar name` entry toggles the relevant text display at the top of the graph
  - The `Assay name` entry toggles the relevant text display of at the top of the graph
  - The `Column name` entry toggles the relevant text display of at the top of the graph
  - The `Minimap` entry toggles the display of a miniature version of the graph for the purposes of navigation and scale awareness
- The `Style` subcategory provides a `Save` and `Load` function for the symbology profile to/from either the database of a .json file.    

#### Discrete spherical data

   :::{note}
   The `Discrete spherical data` feature is only available to OpenLog Premium subscribers.
   :::

In the case of discrete spherical data, a series of tadpole markers display to the right side of the visualization panel.

   ```{image} images/depth_viz_15_spherical.png
   :alt: depth_viz_15_spherical
   :class: bg-primary
   :width: 400px
   :align: center
   ```

##### Spherical symbology

Symbology of discrete spherical data is identical to that of [Discrete polar data](#discrete-polar-data)

#### Extended numerical data

Extended numerical data is handled the same way as discrete numerical data except that the view is set to bar chart mode by default.

   ```{image} images/depth_viz_07_numerical_symbology_2.png
   :alt: depth_viz_07_numerical_symbology_2
   :class: bg-primary
   :width: 300px
   :align: center
   ```

#### Extended categorical data

In the case of extended categorical data, a series of interval logs display to the right side of the visualization panel.

   ```{image} images/depth_viz_08_categorical_symbology.png
   :alt: depth_viz_08_categorical_symbology
   :class: bg-primary
   :width: 750px
   :align: center
   ```

- The `Bar pen` category encompasses all symbology parameters related to bar chart elements
  - The `Color` parameter sets the HSV or RGB values of bar outlines

   ```{image} images/depth_viz_07_numerical_symbology_5.png
   :alt: depth_viz_07_numerical_symbology_5
   :class: bg-primary
   :width: 200px
   :align: center
   ```

  - The `Width` parameter sets the thickness of bar outlines
  - The `Style` parameter sets the pattern of bar outlines, the available options are: `CustomDashLine`, `DashDotDotLine`, `DashDotLine`, `DashLine`, `DotLine`, and `SolidLine`
  - The `Cap Style` parameter sets the shape of the ends of bar outline segments as defined by the `Style` parameter, the available options are: `Flat`, `Round`, and `Square`
  - the ![](icons/icon_manage_symbology.svg) parameter provides access to the pattern/color fill tables. Each table matches a `Key column` taken from the variable table to a symbology:

   ```{image} images/depth_viz_08_categorical_symbology_1.png
   :alt: depth_viz_08_categorical_symbology_1
   :class: bg-primary
   :width: 400px
   :align: center
   ```

  - The `Pattern` tab links to the SVG files that make up the pattern
  - The `Color` tab sets the HSV or RGB values of the background
  - The `Scale` tab defines the relative size of the pattern


   ```{image} images/depth_viz_07_numerical_symbology_5.png
   :alt: depth_viz_07_numerical_symbology_5
   :class: bg-primary
   :width: 200px
   :align: center
   ```

#### Extended imagery data

In the case of extended imagery data, a series of core images display to the right side of the visualization panel.

  ```{image} images/depth_viz_09_imagery_1.png
   :alt: depth_viz_09_imagery_1
   :class: bg-primary
   :width: 750px
   :align: center
   ```

- The `Imagery` category encompasses all symbology parameters related to an imagery representation
  - The `Min. width (px)` parameter sets the minimum image width in pixels on screen byond which any zooming out or graph resizing action will have no effect
  - The `Max. stretch factor` parameter defines the aspect ratio beyond which graph resizing action will have no effect

### Compositions

Compositions enable users to display multiple downhole data series from a single table onto a single plot.

#### Composition templates

Composition templates hold the attributes of a composition for reuse. 
They are handled via the `Template manager` which provides an interface to:
- create/delete/edit composition templates
- define composition templates, down to symbology options
- store composition template to an `XplorDB` database

#### Composition template management

To access the  `Template manager` directly go to `OpenLog` > `Data` > `Manage` > `Composition templates`

  ```{image} images/composition_templates_01.png
   :alt: composition_templates_01
   :width: 300px
   :align: center
   ```

The `Template` section of the `Template manager` contains a table with 2 columns to which entries may be added, removed, or edited:
- The `Name` column lists unique string identifiers for each template
- The `Type` column presents a drop-down list with three options: `multiplot`, `crossplot`, and `stacked bar chart`

The `Definition` section of the `Template manager` presents a set of two tables:
- The leftside table contains 3 selectable columns from which a single entry may be selected at a time:
   - The `Table` column lists table names from the drillhole database
   - The `Domain` column indicates the authorized input set of the table
   - The `Extent` column indicates the supported input set of the table
- The righside table contains 2 selectable columns from which any number of entries may be selected at a time:  
   - The `Variable` column indicates the name of each variable relevant to the selection state of the leftside table
   - The `Unit` column indicates the measurement units for each variable

The `Style` section of the `Template manager` displays a standard [`Symbology parameters`](#symbology-parameters) interface for each variable relevant to the selection state of the rightside table

```{image} images/composition_templates_02.png
:alt: composition_templates_02
:width: 600px
:align: center
```   

To add an entry:
1. click the ![](icons/add.svg) icon in the `Template` section of the `Template manager`
2. input a name in the `Name` column
3. select the desired option in the `Type` column, the available options are `multiplot`, `crossplot`, and `stacked bar chart`
   ```{image} images/composition_templates_03.png
   :alt: composition_templates_03
   :width: 300px
   :align: center
   ```

4. select a database table from the leftside list of the `Definition` section of the `Template manager`
5. select at least 2 variable fields from the rightside list, be aware that `stacked bar chart` require variables to be quantified homogeneously
6. set the [`Symbology parameters`](#symbology-parameters) for each variable as required in the `Style` section of the `Template manager`
   ```{image} images/composition_templates_04.png
   :alt: composition_templates_04
   :width: 300px
   :align: center
   ```   
7. click the ![](icons/save.svg) icon in the top right corner of the `Template` section and respond to the confirmation prompt, you may also cancel with ![](icons/cancel_edit.svg)

To remove an entry:
1. select an entry from the list in the `Template` section of the `Template manager`
2. click the ![](icons/remove.svg) icon in the `Template` section of the `Template manager` and respond to the confirmation prompt

To edit an entry:
1. select an entry from the list in the `Template` section of the `Template manager`
2. proceed through steps 2 to 6 of the addition procedure

#### Multiplots

Multiple Extended or Discrete numerical data series may be displayed over the same graph, to do so:

1. Switch the view panel to `Composition` and click the ![](icons/add_assay.svg) icon at the top to summon the `Template manager`
2. Pick a entry of the appropriate `Type` from the `Template` section of the `Template manager`, you may add, remove, edit entries as normal here

   ```{image} images/composition_display_02.png
   :alt: composition_display_02
   :class: bg-primary
   :width: 400px
   :align: center
   ```
3. Click `Load`, the selection tree then shows the `Name` of the `Template` under the relevant `Type` category
4. Select the newly created item in the selection tree and click the `Display` below, 3 options are given:
   ```{image} images/composition_display_01.png
   :alt: composition_display_01
   :class: bg-primary
   :width: 200px
   :align: center
   ```
   - the `From visible plots` applies the `Template` to any driholle that has got at least one regular `Plot` visible
   - `From QGIS selection` applies the `Template` to any driholle that is selected from the `Collar` layer
   - `From custom selection` summons the custom selection interface
   
   ```{image} images/composition_display_03.png
   :alt: composition_display_03
   :class: bg-primary
   :width: 400px
   :align: center
   ```

5. The graph draws to the right of the panel with symbology options as described in the [Discrete numerical data](#discrete-numerical-data) section

   ```{image} images/stack_graphs_04_display.png
   :alt: stack_graphs_01_menu
   :class: bg-primary
   :width: 400px
   :align: center
   ```

#### Crossplots

:::{note}
Crossplots are only available to OpenLog Premium subscribers.
:::

Discrete numerical data series may be plotted against one another over the same graph, to do so:

1. Proceed through steps 1 to 4 of the [`Multiplots`](#multiplots) section
2. A new graph with both data series plotted against one another will appear in the data visualization panel under the `Crossplots` section with the following symbology options:

- The `Point` category encompasses symbology parameters related to the styling of the data points as described in the [Line chart mode](#line-chart-mode) subsection
- The `Regression line` category toggles the display of a linear regression line and includes all symbology parameters related to a line as described in the [Line chart mode](#line-chart-mode) subsection. In addition:
   - The `Display statistics` entry toggles the display of the affine coefficients for the line
- The `Plot options` category groups parameters that control graph-wide elements:
   - The `X grid` and `Y grid` entries toggle the display of a regular grid over the plot space for the X and Y axes, respectively
   - The `Log x` and `Log y` entries  toggle the x and y axes to a decimal log scale, respectively
   - The `Swap axes` entry flips the bearing axes of the variables
- The `Filter` category toggles the display of points to be restricted to the current map selection, more specifically:
   - The `Selected holes` entry sets the filter to match the current map selection
   - The `Custom selection` entry provides a toggle list to set a user-defined filter
- The `Cross symbology` category encompasses symbology parameters related to the colour and size of the points.
   - The `Color ramp` subcategory includes symbology parameters related to value-dependent color styling of the points as described in the [Line chart mode](#line-chart-mode) subsection as well as a `Variable` entry to pick the target
   - The `Symbol size` subcategory defines which `Variable` controls point radii 

   ```{image} images/stack_graphs_07_display.png
   :alt: stack_graphs_01_menu
   :class: bg-primary
   :width: 350px
   :align: center
   ```   
   
#### Stacked plots

:::{note}
Stacked plots are only available to OpenLog Premium subscribers.
:::

Extended numerical data series may be plotted as a bar chart stack over the same graph, to do so:

1. Proceed through steps 1 to 4 of the [`Multiplots`](#multiplots) section
2. A new graph with the data series stacked on top of another will appear in the data visualization panel under the `Stacked plots` section with the following symbology options:
- the ![](icons/icon_manage_symbology.svg) parameter provides access to the `Stack symbology` wizard:
  - the `Order and selection ` tab allows the selection of eligible variable by moving entries left or right between the `Available` and `Displayed` tables using the ![](icons/arrow_left.svg)![](icons/arrow_right.svg) icons, respectively. The ordering is set using the ![](icons/arrow_up.svg) ![](icons/arrow_down.svg) icons for single rank upgrades and downgrades and the ![](icons/double_arrow_up.svg) ![](icons/double_arrow_down.svg) icons for ultimate rank upgrades and downgrades

   ```{image} images/stack_chart_03.png
   :alt: stack_chart_03
   :class: bg-primary
   :width: 450px
   :align: center
   ```   
  - the `Bar fill` tab displays a table with 2 columns where the `Color` sets the HSV or RGB values for each `Variable`

   ```{image} images/stack_chart_04.png
   :alt: stack_chart_04
   :class: bg-primary
   :width: 450px
   :align: center
   ```   

- The `Plot options` category groups parameters that control graph-wide elements:
  - The `Plot name` entry toggles the relevant text display at the top of the graph
  - The `Collar name` entry toggles the relevant text display of at the top of the graph
  - The `Series name` entry toggles the relevant text display of at the top of the graph
  - The `Legend` parameter toggles an on-graph legend for the bar fill
  - The `Minimap` entry toggles the display of a miniature version of the graph for the purposes of navigation and scale awareness
- The `Bar pen` category encompasses all symbology parameters related to bar chart elements
  - The `Color` parameter sets the HSV or RGB values of bar outlines

   ```{image} images/depth_viz_07_numerical_symbology_5.png
   :alt: depth_viz_07_numerical_symbology_5
   :class: bg-primary
   :width: 300px
   :align: center
   ```

  - The `Width` parameter sets the thickness of bar outlines
  - The `Style` parameter sets the pattern of bar outlines, the available options are: `CustomDashLine`, `DashDotDotLine`, `DashDotLine`, `DashLine`, `DotLine`, and `SolidLine`   

   ```{image} images/stack_chart_02.png
   :alt: stack_chart_02.png
   :class: bg-primary
   :width: 400px
   :align: center
   ```   


### Symbology configuration file

OpenLog provides a mean to retain, transfer, and exchange full symbology sets for all types of data via .json files.

To create, edit, or import a symbology file:

1. In the top right corner of the visualization panel, click the `Symbology` drop down menu

  ```{image} images/symbology_file_01_menu.png
   :alt: symbology_file_01_menu
   :class: bg-primary
   :width: 200px
   :align: center
   ```

2. Select the appropriate action:

   - `Load` will prompt the user to browse to an existing symbology configuration file
   - `Save As` will prompt the user to save a new symbology configuration file at a chosen location

## Custom projected CRS creation and management

OpenLog offers an interface to generate custom Cartesian CRS for local positioning applications where regular projected coordinate sets are impractical.

To generate a new custom CRS:

1. Go to `OpenLog menu` -> `Local grid` to open the `Local grid creation` window
2. Input a name in the `Name` text box
3. Select a CRS from the `Base CRS` drop down list, preferably that of the project
4. Pick either `Reference points` or `Origin and direction`
   - When `Reference points` is selected, a 6 column table will appear in the middle section of the window, users may then digitize points over the canvas. The coordinates attached to these points will be displayed in the table under the `Source Easting`, `Source Northing`, and `Source Elevation` columns.  
   Each point may then have its coordinate reassigned under the `Destination Easting`, `Destination Northing`, and `Destination Elevation` columns. The coordinate pairs are then used to calculate a transformation matrix that is applied to the base CRS in order to generate the newly made custom CRS

   ```{image} images/local_grid_01_menu.png
   :alt: stack_graphs_01_menu
   :class: bg-primary
   :width: 400px
   :align: center
   ```

   - When `Origin and direction` is selected, 5 numerical parameters which define the basic mathematical elements of a Cartesian coordinate system will be made available to the user. The parameters are `X`, `Y`, `Rotation`, `X Scale`, and `Y Scale`.  
   The user may point and click an origin point over the canvas to update the `X` and `Y` values. A set of axes with default orientation SN-WE and scale 1000 will appear at the marked location. The axes pair may then be rotated freely with the `Rotation` parameter as well as rescaled and inverted with the `Scale` and `Invert` parameters, respectively

   ```{image} images/local_grid_02_menu.png
   :alt: stack_graphs_01_menu
   :class: bg-primary
   :width: 600px
   :align: center
   ```

5. Click `Create WKT` then `Add to local projection`

   ```{image} images/local_grid_04_menu.png
   :alt: stack_graphs_01_menu
   :class: bg-primary
   :width: 600px
   :align: center
   ```

6. The newly created CRS may be found in the relevant `Project Properties` in the `CRS` category under the `User Defined Coordinate Systems` section at the bottom of the `Prefefined Coordinate Reference Sytems` table

   ```{image} images/local_grid_04_menu.png
   :alt: stack_graphs_01_menu
   :class: bg-primary
   :width: 400px
   :align: center
   ```

## Orthographic data projection

OpenLog may display color coded orthographic projections of downhole data onto both the `2D Map View` and `Cross-section` canvases.

Note that, in the case of numerical data, a suitable [color ramp](#symbology) must have been set beforehand.

### Colour coded line projection

To project downhole data as a colour coded line:

1. Select the downhole data variable of interest
2. click on the ![](icons/trace_symbology_2.svg) icon at the top of the `Display depth data` panel and select a trace type to project to:

   ```{image} images/project_data_01_menu.png
   :alt: stack_graphs_01_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

3. a new line layer will then be added to the project and displayed with matching `Log Viewer` color codes for every sub-variable

   ```{image} images/x-section_viz_02_map.png
   :alt: stack_graphs_01_menu
   :class: bg-primary
   :width: 800px
   :align: center
   ```
### Colour coded bar chart projection

:::{note}
The bar chart projection feature is only available to OpenLog Premium subscribers.
:::

#### Bar chart to map

To project downhole data as a bar chart:

1. Select the downhole data variable of interest
2. click on the ![](icons/barchart_symbology.svg) icon at the top of the `Display depth data` panel and select a trace type to project to:

   ```{image} images/project_data_02_menu.png
   :alt: project_data_02_menu
   :class: bg-primary
   :width: 250px
   :align: center
   ```

3. a new line layer will then be added to the project and displayed with matching `Log Viewer` color codes for every sub-variable

   ```{image} images/project_data_03_map.png
   :alt: project_data_03_map
   :class: bg-primary
   :width: 800px
   :align: center

## Cross-sections

:::{note}
The cross-section feature is only available to OpenLog Premium subscribers.
:::

OpenLog packages its own cross-section tool dedicated to mining industry applications and no longer relies on or recommends the use of the native [Elevation Profile](https://docs.qgis.org/3.44/en/docs/user_manual/map_views/elevation_profile.html) feature.

To make a `Cross-section`:

1. Go to `Openlog` > `Cross-section`

   ```{image} images/cross-section_01.png
   :alt: section_01
   :class: bg-primary
   :width: 150px
   :align: center
   ```
2. The `Section view` panel will dock to the bottom, it is comprised of three sections:
   - an edition toolbar in the top left corner
   - a display toolbar in the top right corner
   - a canvas 

   ```{image} images/cross-section_02.png
   :alt: section_02
   :class: bg-primary
   :width: 800px
   :align: center
   ```

3. Click the ![](icons/)(icons/edit_section_trace.svg) button and draw the section trace over the map via left click action or input vertex coordinates directly in the `Vertices` table

   ```{image} images/cross-section_10.png
   :alt: cross-section_10
   :class: bg-primary
   :width: 600px
   :align: center
   ```
4.Right-click into the map to complete the section trace and click the ![](icons/validate.svg) button to validate the section geometry or cancel with ![](icons/cancel_edit.svg)

### Section viewer controls

Global display parameter controls are lined up in the toolbar the top of the `Section view` panel

```{image} images/cross-section_04.png
:alt: cross-section_04
:class: bg-primary
:width: 800px
:align: center
```

#### Section viewer static controls 

Static controls effect single, non-dynamic actions.

##### Edition

The leftside toolbar includes all commands related to the geometry of the cross-section projection box:

- the ![](icons/edit_section_trace.svg) button opens the `Section trace parameters`:
   - the `Edition` section provides a trace digitalization toolkit with the following options:
      - the ![](icons/trace_digitization.svg) button enables left-click direct inputs
      - the ![](icons/insert_vertex.svg) button allows vertices to be inserted into a segment provided that at least two vertices exist already
      - the ![](icons/add_vertex.svg) button allows vertices to be added to the end of a segment provided that at least two vertices exist already
      - the ![](icons/trace_table.svg) button toggles the display of the vertices' coordinates table with options to ![](icons/add.svg) add, ![](icons/remove.svg) remove, and ![](icons/clear.svg) clear items
   - the `Position` section provides controls to move a section trace by `X step` and `Y step` increments using the ![](icons/arrow_up.svg)![](icons/arrow_right.svg)![](icons/arrow_down.svg)![](icons/arrow_left.svg) arrows or freely via drag action with the ![](icons/pan.svg) button
   - the `Projection` section allows the user to set the projection distance in the orthogonal sense

   ```{image} images/cross-section_09.png
   :alt: cross-section_09
   :class: bg-primary
   :width: 400px
   :align: center
    ```

- the ![](icons/show_section_outline.svg) button toggles the display of the sectiont trace outline 
- the ![](icons/zoom_to_section.svg) button centers and focusses the `2D map view` to the section trace outline
- the ![](icons/flip_section.svg) button flips the order of the section trace vertices
- the ![](icons/section_buffer.svg) button toggles the display of the projection distance and enables its edition

##### Display

The rightside toolbar includes all commands related to the symbology of the display area of the `Section viewer`:

- the ![](icons/north_arrow.svg) button toogles the display of the azimuth of the cross-section panels

   ```{image} images/cross-section_06.png
   :alt: cross-section_06
   :class: bg-primary
   :width: 60px
   :align: center
   ```

- the ![](icons/show_section_panel_data.svg) button toggles the display of the coordinates of the section trace vertices

   ```{image} images/cross-section_05.png
   :alt: cross-section_05
   :class: bg-primary
   :width: 60px
   :align: center
   ```

- the ![](icons/show_section_grid.svg) button toggles the display of the grid over the display area and provides access via a dropdown menu to the `Section grid` parameters:
   - the `Spacing` section allows the user to specify the gap between each grid line in the X and Y directions
   - the `Reference` section allows the user to express trace-line coordinates as a `relative` measure based on the starting point or an `absolute` measure based on the active CRS
   - the `Labels` section allows the user toggle the display of coordinate labels and to specify their size

   ```{image} images/cross-section_07.png
   :alt: cross-section_07
   :class: bg-primary
   :width: 200px
   :align: center
   ```

- the 1:1 button toggles the coordinate system of the display between strict Cartesian and X/Y fill   
- the ![](icons/cursor_coordinates.svg) button toggles the display of absolute and relative coordinates in the numerical field to its left

   ```{image} images/cross-section_08.png
   :alt: cross-section_08
   :class: bg-primary
   :width: 200px
   :align: center
   ```

#### Section viewer contextual controls

- The standard [QGIS canvas contextual menu](https://docs.qgis.org/3.44/en/docs/user_manual/map_views/map_view.html#exploring-the-map-view) is accessible via right click action into the display area.

   ```{image} images/cross-section_03.png
   :alt: cross-section_03
   :class: bg-primary
   :width: 300px
   :align: center
   ```

##### Section viewer interactive controls

Interactive controls are accessible by hovering the cursor over the display area:

- Panning is controlled via left click drag action
- Zoom is controlled via M3 wheel action