GeoProfiler – Help

Plugin authors: M. Alberti, M. Zanieri
Concept: M. Zanieri
Implementation: M. Alberti

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.

The GeoProfiler command tree — Fig. 1. The module interface, with the various commands NOT expanded. The current tree is organized as numbered steps (*0 - Create 3D topographic profile* … *6 - Import geoprofile*).

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

This whole step only builds the 3D line layer that carries the topography. If you already have one - generated in an earlier session, or produced by any other means, as long as it is a 3D line layer - just load it into QGIS and go straight to step 1.

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

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.
Create 2D profile trace: Load trace from 2D line layer, or Digitize 2D trace in canvas.
Define DEM as elevation source: one of the single-band rasters loaded in the project.
Generate 3D profile: samples the DEM along the trace and writes the 3D line(s) to the storage layer, each named profile 1, profile 2, ... in a profile_name field.

A 3D line layer created here carries a profile_name text field, filled with a progressive name as each profile is written and continued when more are appended later. It is an ordinary attribute: rewrite it in the QGIS attribute table to call a profile what you call it on the map, and Section Editor will title its section with that. A layer created by an earlier version, or brought in from elsewhere, simply has no such field - it can still take generated profiles, only without a name.

The storage is mandatory, and has to be defined before Generate 3D profile is run: it is where the profile is written. Without it the run has nowhere to write and the profile is lost - the tool still reports the profile as generated, and only the "qgSurf" log panel records that nothing was stored.

1. Choose the working profile

Load the 3D line layer into QGIS, if it is not already there
Run 1 - Choose 3D topographic profile, choosing there also, if the layer carries one, the field naming each profile

This is the first step for everyone: whether the 3D layer was just generated in step 0 or brought in ready-made, it becomes the reference geometry only once it is chosen here.

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

Skipping this plots everything with the default styles.

4. Plot

Run 4 - Plot geoprofile

You now have a geological profile.

5. (Optional) Save your work

5 - Export geoprofile
Save graphical parameters

Reload later with 6 - Import geoprofile.

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

The plot is a pure result, not stored.

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.

This section is only needed to build a topographic profile. A 3D line layer you already have - from an earlier session, or produced outside the plugin - is used as it is: load it into QGIS and carry on from 1. Working Profile Layer.

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

Mandatory, and to be done before Generate 3D profile: a generated profile with no storage defined has nowhere to be written and is lost. The run still reports the profile as generated; only the "qgSurf" log panel records that nothing was stored.

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.

Profiles settings — Fig. 6. Definition of the profile parameters. In this example 5 parallel profiles will be created with a spacing of 200 units (depending on the CRS, meters, feet or others). The dialog now also carries *Grid-sampling spacing within profile*, i.e. the spacing at which the DEM is sampled along the trace, proposed as the DEM cell size, which is the finest spacing that still adds information.

Parallel profiles

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

Fig. 7. Example of topographic profiles created with the parameters defined in the previous figure. Data: TinItaly, Mount Alpi (Southern Italy). The current default plot names both axes with their quantity and unit, which this screenshot predates.

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.

The dialog also asks, optionally, for a profile name field of that layer: the value it holds for each chosen line becomes the name of the profile, is written to the export, and is what Section Editor titles the section with. The profile_name field of a layer generated here is proposed already chosen; any other field of any other layer can be picked instead. Left on --optional--, or empty for a given line, the profile is named after the feature id of the line it was read from. A geoprofile reimported from an export keeps the names it was exported with.

Redefining the base 3D profile (new line source, DEM, digitized trace, or project reload) clears any previously defined point/attitude/focal mechanism projections and line/polygon intersections, since they were computed against the profile just discarded. Redefine the geological data stages afterwards.

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.

Point projection dialog — Fig. 8. Example of point projections UI. The current dialog offers the three elevation sources (DEM, z field, 3D points), the depth controls described above and the DEM used for depths below topography.

Fig. 9. Seismic hypocenters of the 2007 Colfiorito sequence (Central Apennines) plotted in parallel profiles. Worth retaking with the depths read as such and the vertical axis labelled as a depth in km (see Graphical parameters).

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)

Attitude projection dialog — Fig. 10. Geological attitudes projection UI. The current dialog adds the record id/label field and the choice of the elevation source (DEM, z field, 3D points).

Fig. 11. Example of geological attitudes projection along a set of parallel profiles in the eastern sector of Mt. Alpi zone (Basilicata, Southern Italy).

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

Beachballs are rendered through obspy, an optional dependency. If it is not available in the QGIS Python environment, the command reports so as soon as it is invoked: install it (pip install obspy) and restart QGIS.

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.

Fig. 12. The focal mechanism projection dialog.

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

Fig. 13. The beachball style dialog.

Fig. 14. Focal mechanisms plotted on a profile as beach balls.

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.

Line intersection dialog — Fig. 15. Line intersections UI.

Fig. 16. Example of labelled fault intersections, together with seismic hypocenters of the 2007 Colfiorito sequence (Central Apennines).

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.

The colours start from the layer's own symbology and keep following it: recolour a class in QGIS and the next plot, or the next opening of that dialog, shows the new colour. A class you recolour here instead becomes yours, and is no longer overwritten by the layer. Reload from source layer, in the same dialog, gives up those choices and takes the layer symbology as it stands.

Unlike the line intersections, polygon intersections always use the whole layer: a selection in QGIS does not restrict them.

Polygon intersection dialog — Fig. 17. Geological polygon intersection UI. The current dialog asks for the polygon layer only: the classification field is gone, categories being taken from the layer's symbology.

Polygon intersections on parallel profiles — Fig. 18. Example of geological polygon intersection on a profile in the Timpa San Lorenzo zone (Calabria, Southern Italy).

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.

The log panel is the place to look when a layer yields fewer intersections or projections than expected: it names the features that were left out.

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

Polygon categories must match when reloading saved parameters. A style file written before an option existed loads with that option at its default.

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

Data and visualization are decoupled.

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.

The graphic attributes in force when the export is written are saved with the data: the colour of every geological unit, the colours, widths, line styles and markers of the topography and of the projections, and the elevation range and vertical exaggeration of the axes. A profile exploded and restyled on its own carries its own attributes alongside those of the stacked plot. What is saved is what the plot shows at that moment, not what the source layer symbology says now.

The classification of the source layers is saved too, whole: every class of the polygon layer, in the order of its legend and with the colour it is drawn in, and every category of the intersected lines, in the gp_source_categories table. A single profile crosses only some of the classes of the map it is cut from, and the intersection tables can say nothing of the others: this is what lets the Section editor offer the whole classification of the map on every section, and give a unit the same colour in all of them.

Every profile also carries the coordinates that tie it back to the map: each topographic sample is saved with its real-world x and y, and the vertices of the profile trace — the start one, the end one and every direction change in between — are saved in the gp_profile_vertices table with their distance along the profile, their coordinates in the project CRS and their longitude and latitude (EPSG:4326). A profile exported this way can be hooked back onto its map position by any reader of the database.

Import geoprofile

Use:

6 - Import geoprofile

This allows you to:

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

The profiles come back looking as they did when they were exported: Use the graphic attributes exported from GeoProfiler, on by default, puts back the unit colours, the styles of the projections and the axis range, so a geoprofile reopened in a fresh QGIS session is the figure it was, and not a plot recoloured at random. Uncheck it to plot with the styles currently set instead. The option is offered only when the chosen database actually carries the attributes: an export written by an earlier version of GeoProfiler does not.

More than one profile can be imported at once, and the layout of the imported profiles decides how they are plotted: one below the other (vertical, the usual stack), one beside the other (horizontal) or on a grid of the chosen number of columns. On a grid every panel is labelled and graduated on its own, profiles of different lengths being plotted side by side.

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)