Manuale italiano · Home

Photo viewpoint

Commands and dialogs · GIF

Presentation and user manual · experimental version 0.7.6

Presentation

Photo viewpoint is a QGIS plugin for connecting field photographs to their map positions, viewing directions and printed survey documentation. Create a viewpoint in three clicks, or import multiple photographs using their GPS metadata. Assign a code and caption, inspect the original image, adjust the viewpoint with interactive handles, and build photo callouts in print layouts.

Original GPS metadata remains separate from the editable point. A displacement field records the distance from the original GPS position. Reusable styles provide classic rays, an oriented top-view camera, a bearing arrow or a translucent field-of-view sector. The plugin stores ordinary vector attributes and native QGIS layout items, keeping projects editable with familiar tools.

Installation and compatibility

Targets QGIS 3 / Qt 5 and QGIS 4 / Qt 6. The main workflow has been tested on QGIS 4.2.3. Earlier versions were tested by the user on QGIS 3.44.14/macOS. New schema/style portability and copy operations still need desktop validation. Install the ZIP via Plugins → Manage and Install Plugins → Install from ZIP. To update, save your work, disable the plugin, replace it with the new ZIP and restart QGIS.

The internal package remains prese_fotografiche, so this updates the same plugin. The plugin follows the QGIS interface language: Italian when selected, and English otherwise. Documentation is supplied in English and Italian.

Create a layer

Choose Create photo layer. Set the name (default Photo viewpoint), a projected CRS in metres and temporary storage or a new GeoPackage, Shapefile, SQLite or FlatGeobuf file when supported by installed drivers. The saved project's directory is proposed. Existing datasets are not overwritten. For a temporary layer, export data before closing; for file layers, save edits normally. Save the project too.

Field order and text capacity

New plugin-managed fields start with code, caption, distGPS, followed by the other service fields in their previous relative order. A provider may add its own primary key, such as GeoPackage fid; QGIS table ordering keeps the three user fields first.

FieldMeaning
codeViewpoint name/identifier and map label.
captionDescription below code and image filename in layouts. Length 2,000 for new non-Shapefile layers.
distGPSPlanar grid distance in metres from gps_x/gps_y to the editable geometry; NULL if either is missing.
azimuth / fov / distanceGrid bearing (clockwise from north), total FOV, graphic ray length.
photo / noteImage reference and optional notes.
gps_* / exif_*Original image metadata and GPS position transformed to the layer CRS.
vp_statusneeds_pos or positioned, based on geometry availability.
pf_x / pf_y / pf_map / dimX / dimYSaved page position, map identifier and actual photo frame dimensions, in millimetres.

Shapefile DBF text fields have a short byte-based limit. This plugin uses width 254 for SHP captions and cannot guarantee at least 255 Unicode characters. Use GeoPackage for long captions. Existing caption columns are not silently widened or rewritten.

Existing layers and English conversion

Layers with legacy codice and Didascalia remain readable and editable. English aliases and table ordering are applied in QGIS, but the original physical columns and their stored data remain intact.

For a physical English schema, open Apply viewpoint style and select Create English-field GeoPackage copy…. Choose a new file. The copy uses code/caption, long caption capacity and the requested order; the original remains untouched. Select the new layer and regenerate layout photo links for that new layer. Copying creates new feature IDs and a new layer identifier.

Three-click capture

  1. Select the compatible layer and choose Create viewpoint then link photo.
  2. Click the viewpoint position.
  3. Click the viewing direction and graphic ray length.
  4. Click a FOV edge; the opposite edge is symmetric.
  5. Enter a unique code and optionally an image path. Confirm.

Esc cancels the unfinished viewpoint. Backspace returns one step. FOV is 1–179°. Graphic distance does not measure the photographed subject.

Import from photographs

Create viewpoints from photos selects multiple files and shows GPS/bearing status. Default azimuth is 0°, FOV 40°, graphic length 20 m; edit them before importing. Every checked image creates one record. File basenames become codes, with suffixes for duplicates. True-north EXIF direction is converted to grid bearing when usable; magnetic/unknown direction uses the default. FOV and length use defaults.

Uncheck images without usable GPS to exclude them, or keep them as records with NULL geometry. The Photos to position panel lists these records: select one, choose Place on map and click its location. No artificial origin is assigned. You may delete a pending record with confirmation; the image file is never deleted. Refresh list after undo or external edits. Save layer edits and the project.

Edit, preview and EXIF

Edit viewpoint selects a point and exposes handles for position, axis/length and FOV. Drag and release to apply. A click on empty map space deselects the viewpoint and hides handles. Moving geometry does not alter original GPS fields. distGPS uses an apply-on-update QGIS default: save the project to preserve its configuration. Editing a standalone SHP in another program does not run a QGIS expression.

View photo opens an image preview with Open image, Open folder and Change image. Remote URLs open in a browser rather than an internal preview. Change image replaces the reference and refreshes metadata; missing values in the new image are cleared. Read photo metadata refreshes selected records, or all records if none are selected.

Conventional JPEG APP1/TIFF EXIF is read without extra dependencies. Available values include latitude/longitude, altitude/reference, image direction/reference, date, camera and datum. gps_x/gps_y assume WGS84 if no datum is declared; another declared datum is not guessed. HEIC/RAW, MakerNotes and XMP-only GPS are not decoded. No values are invented, no originals are modified, and no photos are uploaded.

Apply viewpoint style

The palette button opens a dialog with preset, symbol size, labels and reusable-style saving:

Applying a style changes the layer's rendering and label settings, not its geometry or survey parameters. The SVG artwork is embedded as base64 in the style, so it does not depend on plugin installation paths.

Reusable styling across projects

New local file layers save a QML sidecar automatically. With Apply viewpoint style, keep Save a reusable QML / database default style enabled to update it. For SHP/FlatGeobuf, the sidecar shares the data basename: survey.shp and survey.qml. Keep them together when copying the dataset. QGIS loads the matching default QML when adding the data.

For GeoPackage/SQLite, a table-specific QML backup is written, and saving a default style inside the dataset is attempted through QGIS. Provider support or file locks may prevent this; read the result message. If the database default is unavailable, load the named QML manually from Layer Properties → Style → Load Style. Save pending layer edits before saving a database default. A project with an already assigned style may continue using that project style until you reload it.

QML preserves QGIS geometry generators, labels, aliases and defaults. SLD is not used as the authoritative export because it cannot faithfully represent all these QGIS-specific components. Styling remains QGIS-specific, not a universal Shapefile property.

Layout photographs

Open Layout Photos from the print layout toolbar and choose a map and layer. Generate / Update refreshes photos, captions and leaders while retaining existing frame positions and sizes. Save the project to retain them. To rebuild missing frames, optionally save positions and sizes to the layer and commit its edits. The fields store one backup per feature, tied to the map. Only new frames without a backup use the initial size and spacing settings. Static layouts in millimetres only.

Testing and publication

Python tests cover metadata, import defaults, missing geometry, rollback, schema resolution, style paths and numeric layout behavior. Native rendering, DB style defaults and GUI operation require real-QGIS testing. The package includes smoke_test_styles.py and other integration tests for the QGIS console.

The supplied homepage and repository materials are drafts. No GitHub repository has been created and no QGIS approval is claimed. Real maintainer email and repository/homepage URLs, cross-platform desktop tests and official review are needed before public release.

Credits and license

Concept, requirements and hands-on testing: Riccardo Casoli. Code, original icons and documentation assistance: ChatGPT / Codex (OpenAI), through iterative collaboration. Human maintainership is required. This is not an official QGIS or OpenAI product. GPL-3.0-or-later; full text in LICENSE.

Commands and dialogs

Screenshots show the actual dialogs with demo data. The appearance and language of native controls depend on QGIS and the operating system. Animated demonstrations.

CommandPurpose
Create new Viewpoints layerCreate an empty layer.
Create viewpoint then link photoThree map clicks, then code and photo.
Create viewpoints from photosImport several images and read GPS.
Photos to positionPlace records without GPS.
Edit viewpointSelect the viewpoint and drag its handles.
Open photo preview (click a viewpoint)Open the full preview with a click.
Apply viewpoint styleChoose a symbol and size.
Read photo metadataRead image metadata again for the layer.
Layout PhotosIn the print layout menu or toolbar.

Create new Viewpoints layer

Layer / file name sets the name. Storage format selects a temporary layer or an available persistent format. CRS must be projected in metres. Directory selects the destination for a persistent file. Confirm with OK.

Create new Viewpoints layer
Create new Viewpoints layer · example

Create viewpoint then link photo

Click the camera location, then a point on the viewing axis (direction and graphic length), then one edge of the field of view (total angle 1–179°). Confirm the unique code and optionally pick a photo. Cancel abandons the new viewpoint. Save the layer edits afterwards.

Create viewpoint then link photo
Create viewpoint then link photo · example

Create viewpoints from photos

The table shows which photos have GPS and which need a manual position. Check the rows to import, or exclude all images without GPS. Set the fallback azimuth, field of view and graphic length. A usable true-north EXIF bearing takes precedence over the default azimuth.

Create viewpoints from photos
Create viewpoints from photos · example

Photos to position

Select an entry in the dock, start placement and click the map. Deleting the row removes the record and leaves the image file on disk.

Photos to position
Photos to position dock

Edit viewpoint

Click the viewpoint. Drag the center circle to move it, the axis square to change bearing and length, or the edge square to change the field of view. Release to apply; press Esc to cancel a drag in progress. Click away from the points to deselect. Save layer edits.

Open photo preview (click a viewpoint)

A local photo thumbnail appears automatically when you hover over a viewpoint in the active layer. Activate this command and click the point for the full dialog. The buttons open the file, open its folder, or change the linked image.

Open photo preview (click a viewpoint)
Open photo preview (click a viewpoint) · example

Apply viewpoint style

Symbol chooses rays, camera, arrow or sector. Symbol size is in millimetres. You can show code labels, save a reusable style, or create a GeoPackage copy with English field names.

Apply viewpoint style
Apply viewpoint style · example

Read photo metadata

Re-read linked photos for the selected viewpoints, or the whole layer if none are selected, to refresh EXIF/GPS attributes without moving the viewpoints. Check the updated attributes and save layer edits.

Layout Photos

Select the map and layer. The millimetre settings control maximum size and spacing for new frames. Under Caption contents and appearance, check and reorder fields; “Image filename” comes from photo. Set font, size, alignment, color and opacity. Generate / Update preserves existing frames; save the project. Save frame positions and sizes to layer creates a backup for missing frames; commit layer edits to retain it.

Layout Photos
Layout Photos · example