Presentation and user manual · experimental version 0.6.0
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.
Target: QGIS 3.28–3.44 with Qt 5; QGIS 4 is not supported. 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. Version 0.6 uses English UI throughout; QGIS native dialogs/buttons still follow QGIS itself. Documentation is supplied in English and Italian.
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.
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.
| Field | Meaning |
|---|---|
| code | Viewpoint name/identifier and map label. |
| caption | Description below code and image filename in layouts. Length 2,000 for new non-Shapefile layers. |
| distGPS | Planar grid distance in metres from gps_x/gps_y to the editable geometry; NULL if either is missing. |
| azimuth / fov / distance | Grid bearing (clockwise from north), total FOV, graphic ray length. |
| photo / note | Image reference and optional notes. |
| gps_* / exif_* | Original image metadata and GPS position transformed to the layer CRS. |
| vp_status | needs_pos or positioned, based on geometry availability. |
| pf_x / pf_y / pf_map / dimX / dimY | Saved 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.
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.
Esc cancels the unfinished viewpoint. Backspace returns one step. FOV is 1–179°. Graphic distance does not measure the photographed subject.
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 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.
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.
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 photos chooses a static layout, map and layer. Maximum width/height fit each image to its own aspect ratio. Existing saved dimX/dimY take precedence. Images can overlap maps and all other graphics. Move/resize the photo frame with native layout handles; caption and leader follow it while the plugin is active. Complete caption in the attribute table and regenerate to refresh text.
Save positions and sizes stores pf_x/pf_y (top-left coordinates from the page's top-left), pf_map and dimX/dimY. Save layer edits and the project. Regenerate after changing map extent, scale, viewpoint geometry, image or description. Atlas, temporal filtering and arbitrary clipping are not supported. Retain original images; they are linked, not copied. Check page overflow, readability and line crossings before export.
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.
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.