GeoProfiler – Help

Overview

GeoProfiler helps you build geological profiles by integrating topography and georeferenced geological data (points, attitudes, focal mechanisms, lines, polygons) into a reproducible workflow.

It is part of qgSurf and evolves from the standalone qProf plugin, with a largely rewritten architecture.

Quickstart (2 minutes)

If you just want to create a geological profile quickly. The steps below are the numbered branches of the command tree (Fig. 1), in the order they are meant to be run, and each command is started by double-clicking it in the tree.

0. Create a 3D topographic profileSKIP IF YOU ALREADY HAVE ONE

Run the four commands under 0 - Create 3D topographic profile (Fig. 2), in this order:

1. Define output storage geopackage: the GeoPackage, and the 3D line layer inside it, that the generated profile will be written to. Pick one of Create new geopackage with empty 3D line layer, Create new 3D line layer in existing geopackage or Append to existing 3D line layer in geopackage.
2. Create 2D profile trace: Load trace from 2D line layer, or Digitize 2D trace in canvas.
3. Define DEM as elevation source: one of the single-band rasters loaded in the project.
4. Generate 3D profile: samples the DEM along the trace and writes the 3D line(s) to the storage layer.

1. Choose the working profile

• Load the 3D line layer into QGIS, if it is not already there
• Run 1 - Choose 3D topographic profile

2. Add geological data

Under 2 - Define geodata to add (Fig. 3), as many as you need:

• Points → Point projection
• Attitudes → Geological attitude projection
• Earthquake focal mechanisms → Focal mechanism projection
• Faults → Line intersection
• Outcrops → Polygon intersection

3. (Optional) Set graphical parameters

• Define graphical parameters, under 3 - Set graphical parameters

4. Plot

• Run 4 - Plot geoprofile

5. (Optional) Save your work

• 5 - Export geoprofile
• Save graphical parameters

Minimal requirements

• A 3D line layer holding the topographic profile

or, to build one in step 0:

• A DEM
• A line (or a digitized trace)
• A GeoPackage to store the profile in

Quick Example (field use)

Create a GeoPackage to store the profile in, digitize a profile across an Apennine ridge, select a DEM, and generate the 3D profile. Choose it as the working profile, then project bedding attitudes and intersect mapped fault traces. Plot the profile to visualize the relationships between stratification and tectonic structures.

Next time, with the 3D profile layer already in the GeoPackage, the same section is replotted by loading that layer and choosing it as the working profile - no DEM sampling involved.

Workflow Overview (visual)

          ┌── step 0: only if you have no 3D profile layer yet ──┐
          │                                                      │
          │  [Storage geopackage]     [Trace (2D/3D)]     [DEM]  │
          │           │                      │              │    │
          │           └───────────┬──────────┴──────────────┘    │
          │                       ▼                              │
          │              Generate 3D profile                     │
          └───────────────────────┬──────────────────────────────┘
                                  ▼
                         [3D profile layer]  ◀── or one you already have
                                  │
                                  ▼
                       Choose working profile
                                  │
                                  ▼
                         Add geological data
                         ├─ Points (projection)
                         ├─ Attitudes (projection)
                         ├─ Focal mechanisms (projection)
                         ├─ Lines (intersection)
                         └─ Polygons (intersection)
                                  │
                                  ▼
                                Plot
                                  │
                          ┌───────┴────────┐
                          ▼                ▼
                  Export geoprofile   Save style
                          │                │
                          └───────┬────────┘
                                  ▼
                          Import geoprofile

Core Concept

GeoProfiler is built around two geometric elements:

• Topographic line → the 3D profile trace sampled from the DEM
• Profile plane → a vertical plane orthogonal to the profile trace

Data behavior

• Projected data
  • Points
  • Geological attitudes
  • Earthquake focal mechanisms
  projected onto the profile plane
• Intersecting data
  • Lines (faults)
  • Polygons (outcrops)
  intersect the topographic line

Mental Model (important)

All outputs depend only on:

• profile geometry
• geological data
• graphical parameters

0. Creating Topographic Profiles

Profiles are stored as 3D line layers in a GeoPackage, and are created with the commands under 0 - Create 3D topographic profile (Fig. 2), run in the order they are listed in: storage, trace, elevation source, generation.

Define the output storage

Where the generated profile will be written: a GeoPackage, and a 3D line layer inside it. One of:

• Create new geopackage with empty 3D line layer
• Create new 3D line layer in existing geopackage
• Append to existing 3D line layer in geopackage

Define the trace

• Load trace from 2D line layer (an existing 2D or 3D line layer)
• Or Digitize 2D trace in canvas, with Clear last trace / Clear all traces to correct it

Define elevation

• Define DEM as elevation source, choosing among the single-band rasters loaded in the project

Generate the profile

Generate 3D profile samples the DEM along the trace and writes the resulting 3D line(s) to the storage layer.

Parallel profiles

• Number must be odd (1, 3, 5, …)
• Generated symmetrically around the base trace

1. Working Profile Layer

Load the 3D line layer into QGIS and select:

1 - Choose 3D topographic profile

This defines the reference geometry for all operations.

2. Geological Data Integration

Each stage below (points, attitudes, focal mechanisms, lines, polygons, see Fig. 3) runs its own projection/intersection immediately once its dialog is confirmed - there is no separate "create/apply" step: define a stage, and its result is computed and added to the geoprofile right away, ready to be re-plotted. A progress bar follows the run, which for large datasets advances per block of points over the whole set of profiles.

2.1 Point projections

Inputs:

• Point layer
• Vertical position, from one of: a DEM, a z field of the layer, or the 3D geometry of the points themselves
• Maximum distance from the profile trace
• Label field

Depths instead of elevations

When the vertical value is read from the layer (a field, or the point geometry), it can be declared a depth rather than an elevation, which is the usual form for hypocentres:

• Values are depths, not elevations
• Depth measured from: sea level (default) or the topographic surface (DEM), in which case a DEM supplies the surface the depth hangs from
• Depth unit: km (default) or m

The values are converted into the elevation the profiles are drawn in; the plot itself keeps working in metres of elevation. The controls do not apply to the DEM option, which already yields an elevation, and are therefore disabled there.

2.2 Attitude projections

Inputs:

• Point layer
• Azimuth field, read as dip direction or as RHR strike
• Dip angle field
• Label field
• Vertical position: DEM, z field, or 3D points
• Maximum distance from the profile trace

Output:

• Marker + segment representing plane–profile intersection (the apparent dip on the profile plane)

2.3 Focal mechanism projections

Earthquake focal mechanisms are projected like attitudes - the fault plane is an attitude - and drawn as beachballs.

Inputs:

• Point layer storing the focal mechanisms
• Fault plane azimuth field, read as RHR strike (the default, being the convention mechanisms are catalogued in) or as dip direction
• Fault plane dip angle field
• Rake field, in the Aki & Richards convention: this is what turns a plane into a double-couple mechanism, so it is mandatory here
• Record id/label field
• Vertical position: z field (the default), 3D points, or a DEM; with the depth controls of §2.1, which here are on by default, since hypocentral depths are catalogued as depths in km below sea level
• Maximum distance from the profile trace

Records whose azimuth, dip or rake are missing or non-numeric are skipped and reported in the QGIS log panel, so a few bad rows do not stop the run.

Beachball style

Under Define graphical parameters → Focal mechanism projections:

• Beachball view: Map view (as catalogued), i.e. the lower-hemisphere projection as it would be drawn on a map, or Section view (rotated into the profile plane), i.e. the mechanism as seen from the profile plane
• Beachball size, in points, so that beachballs stay circular whatever the vertical exaggeration of the profile
• Colours of the compressional and dilatational quadrants, and of the outline
• Alpha (opacity) and optional id labels

2.4 Line intersections

• Input: line layer, plus the field labelling each line (e.g. the fault name or type)
• Output: points along the topographic profile, labelled with that field

If the layer has a selection, only the selected features are intersected.

2.5 Polygon intersections

• Input: polygon layer
• Output: intersections along the profile, classified by the categories of the layer's QGIS symbology: each intersection takes the label of the legend entry the polygon is drawn with, so the profile follows the map legend

The colour of each category is then set under Define graphical parameters → Polygon intersections.

2.6 Records that cannot be read

Source layers are rarely spotless. Features with a null or empty geometry, and parts with too few points to define a line, are skipped and reported in the QGIS Log Messages panel, under the qgSurf tab, one message per feature: the stage carries on with the remaining ones instead of failing as a whole. A stage fails, with an explicit message, only when nothing usable is left in the layer.

3. Graphical Parameters

Controls the appearance of the plot, under 3 - Set graphical parameters → Define graphical parameters:

• Figure parameters: width and height, in inches
• Plot elevation parameters:
  • vertical exaggeration
  • z max and z min values, honoured exactly as given
  • Vertical axis unit: m or km
  • Label as depth, positive downwards: the axis is annotated as a depth, the way hypocentres are catalogued. The plotted values are untouched, they stay elevations in metres - only the annotation changes, so leave it off for an ordinary geological profile carrying topography above sea level
  • Max vertical tick labels: an upper bound per profile (five by default), since a count that reads well on one plot becomes a wall of numbers over nine stacked ones
  • Along-profile distance unit: m or km, set independently of the vertical one
  • Name the axes and their units on the figure: on by default
• Plot styles, one dialog per data type: topographic elevations, point projections, attitude projections, focal mechanism projections, line intersections, polygon intersections

Persistence

• Save graphical parameters
• Load graphical parameters

4. Plot

Run:

4 - Plot geoprofile

• Uses default parameters if none are defined
• Automatically reflects any change in data or graphical parameters
• Save figure writes the plot to file

Exploding a single profile

The stacked plot splits its vertical room between every profile, so with nine of them each panel is a sliver. The Explode chooser on the plot window lists the profiles by the same numbers the stacked plot labels its panels with: pick one and it opens in a window of its own, with the full height to itself. Several exploded profiles can stay open side by side for comparison.

Each exploded window carries its own Graphical parameters button, which restyles and redraws that profile alone. Its parameters start as a copy of the stacked plot's, so the window opens looking like the panel it came from and diverges only where it is changed.

5 and 6. Export and Import (Reproducibility)

Key idea

• Export stores data
• Graphical parameters are stored separately

Export geoprofile

Use:

5 - Export geoprofile

This saves:

• projected points
• projected attitudes
• projected focal mechanisms
• line intersections
• polygon intersections

Into a database file: SQLite by default (.sqlite/.db), or GeoPackage (.gpkg) if preferred. Either the whole set of profiles or a chosen subset of them can be exported, under a named result set.

Import geoprofile

Use:

6 - Import geoprofile

This allows you to:

• reload previously computed data
• restore a working session
• re-plot without recomputing

Why this matters

• Reproducible workflows
• Reusable datasets
• Shareable results
• Independent styling

Current Limitations

• No GPX input
• No slope calculation
• Focal mechanism plotting requires the optional obspy package

Design Philosophy

GeoProfiler is designed to be:

• Reproducible
• Modular
• Flexible (supports non-linear and parallel profiles)