geoGPS QGIS plugin – user manual
The geoGPS QGIS plugin connects QGIS with the geoGPS Cloud. It lets you load into QGIS the objects collected with the geoGPS mobile app, edit them, add new ones, handle photos, and import and export data. Changes are saved on the server straight away and are visible in the mobile app and in the web panel (https://geogps.cloud).
This manual applies to version 1.4.14 and follows the order of work: installation → signing in → choosing a project → working with objects → tools and measurements → import and export.
Table of contents
Part I – Getting started
Part II – Project and layers
Part III – Working with objects
- Adding a new object
- Editing an object
- Photos
- Changing geometry
- Object list
- Tools
- Coordinates and measurements on the map
Part IV – Data exchange
Part V – Other
Part I – Getting started
1. Requirements
- QGIS 3.22 or newer (the plugin works with QGIS 3 and QGIS 4), on Windows, macOS or Linux.
- Internet access — the plugin connects to the server
https://geogps.cloud/api(the address is fixed). - An account in the geoGPS system and an active subscription for the organization. The plugin is part of every package.
- A phone with the geoGPS app, or access to the account's e-mail inbox — to receive the login code.
2. Installation and update
Installation
- Download the plugin ZIP file.
- In QGIS choose Plugins → Manage and Install Plugins → Install from ZIP.
- Select the downloaded file and click Install Plugin.
- Make sure the "geoGPS QGIS" plugin is ticked on the list of installed plugins.
After installation the geoGPS toolbar appears, along with the geoGPS item in the Plugins menu.
Update
- Close QGIS and delete the old plugin folder from the QGIS profile.
- Start QGIS and install the new version from the ZIP file, as above.
- Restart QGIS.
Interface language
The plugin works in Polish or English — by default it follows the QGIS language. To change it:
- Choose Plugins → geoGPS → Język / Language.
- Choose Automatic (QGIS language), Polski or English.
- Restart QGIS — the change takes effect after a restart.
3. The geoGPS toolbar
All functions are available from the geoGPS toolbar and from the Plugins → geoGPS menu. The toolbar icons are split by separators into groups: account and data, drawing, object, tools, measurements, session.
| Icon | What it does | When it is active |
|---|---|---|
| Login | Signing in to the geoGPS Cloud. | Before signing in. |
| Projects | Project list, choosing the active project, creating, editing, deleting and importing projects. | After signing in. |
| Objects | List of the active project's objects, import, export. | After signing in and choosing a project. |
| New point | Adding a point by clicking on the map. | After signing in and choosing a project. |
| New line | Adding a line. | After signing in and choosing a project. |
| New area | Adding an area. | After signing in and choosing a project. |
| Edit object | Clicking an object on the map opens its editing; clicking a photo marker opens the photo preview. | After signing in. |
| Label objects | Choosing what the object labels on the map show. | After signing in. |
| Rotate symbol | Rotating the symbol of a selected point (saves its azimuth). | After signing in. |
| Average | Averaging several selected points, saved as a new point. | After signing in and choosing a project. |
| Offset (parallel line) | A copy of a line shifted sideways or along height H. | After signing in and choosing a project. |
| Extend line | Extending a line by a given length from the selected end. | After signing in and choosing a project. |
| Perpendicular segment | A segment of a given length perpendicular to a line. | After signing in and choosing a project. |
| Coordinates | Reading the coordinates of the clicked place and copying them to the clipboard. | After signing in. |
| Measure distance | Measuring a length on the map, without saving an object. | After signing in. |
| Measure area | Measuring an area on the map, without saving an object. | After signing in. |
| Log out | Logging out and removing the geoGPS layers from QGIS. | After signing in. |
| Information | Version, sign-in status, description of the system. | Always. |
The Język / Language item is available in the menu only (chapter 2).
Icons that cannot work at a given moment are greyed out. The tooltip shown on mouse hover tells you what to do (sign in or choose a project).
These functions are not in the plugin: Surfaces, Volume, GML layers and GML export are in the mobile app, and IFC export, PDF reports of objects and projects and exporting a whole project to ZIP are in the web panel.
4. Signing in
Signing in takes two steps.
- Click Login. The geoGPS splash screen appears, followed by the login window.
- Enter your login or e-mail and password ("Show" reveals the password) and click Sign in. With Remember login ticked, the login is suggested the next time you sign in; the password is not remembered.
- The server sends a 6-digit code: by e-mail to the account address and as a push notification to the geoGPS app on your phone. The code is valid for 3 minutes.
- In the Login code window enter the code and click Confirm. The window shows where the code was sent and a countdown.
Special cases:
- Wrong code — the window stays open and shows the number of attempts left.
- The code expired or you ran out of attempts — click Resend code; you do not need to enter the password again.
- Too many attempts — the server temporarily blocks signing in with a code; try again later.
- The session expired while working — the plugin shows "Sign in again". OK opens the login window, Cancel logs you out (removes the token and the geoGPS layers).
- After the Terms of Service or the Privacy Policy change, you must accept them (in the mobile app or in the web panel) to keep using the account.
The organization and user identifiers are fetched automatically when you sign in — you do not need to enter them anywhere.
Part II – Project and layers
5. Basic terms
| Term | Meaning |
|---|---|
| Project | A set of objects with its own coordinate system and geoid model. |
| Active project | The project whose objects are loaded into QGIS and to which new objects are added. |
| Object | A point, line or area with a name, description, attributes and photos. |
| Object type | An object category (e.g. "Hydrants") that determines how it looks. In QGIS every type is a separate layer. |
| Geometric data | The measurement record of each point: B/L, X/Y in the project's coordinate system, heights, accuracy, measurement status. |
| Object attributes | Any key–value pairs added to an object. |
6. Projects and the active project
- Click Projects. The list shows the organization's projects with these columns: name, status, coordinate system (e.g. "ETRF2000-PL / CS2000/21 (EPSG:2178)"), geoid model, update date, author, number of objects and number of photos.
- The list can be searched (name, status, author), and sorted by clicking a header. The active project is highlighted.
- Click a project and choose Set as active (or double-click it).
After a project is chosen:
- the plugin loads its objects into QGIS,
- the map is set to fit all the project's objects with a margin; with a single point the map is centered on it at a scale of 1:1000; a project without objects does not change the view,
- the Objects, New point, New line and New area icons become available.
A project with the "blocked" status can be set as active, but its objects are not loaded — the plugin shows "The active project is blocked - its objects are not loaded."
New project
- In the Projects window click the New project icon above the table (the last of three icons: delete, import, new).
- Enter the project name, choose the coordinate system with the Change… button (a system from the EPSG database) and the geoid model — the list contains the models for the area of the chosen system. The description is optional.
- Click Save.
Editing and deleting a project
- The edit icon in the Actions column opens the Edit project window: name, status (active / blocked), coordinate system, geoid model, description.
- Someone else's project opens as View project — you can edit and delete only your own projects.
- Deleting: select projects with the checkboxes in the first column (they are shown only next to your own projects) and click the Delete selected projects icon. A project is removed together with all its objects and photos — this cannot be undone.
Importing a project (ZIP)
- Click the Import project (ZIP) icon above the table.
- Choose the ZIP file created by a project export in the web panel.
- The plugin shows the number of imported objects and photos (and of skipped ones, if the file contained invalid data).
An import always creates a new project on your account — it does not overwrite existing ones. Exporting a whole project to a ZIP is done in the web panel.
7. geoGPS layers in QGIS
- Objects go into separate layers by object type (e.g. "Hydrants", "Wells"), not into a single layer of points, lines and areas.
- The layers are in the Layers panel, in a group named after the active project.
- Every layer has the style of its type from the server: color, line width, symbol size, transparency — the objects look the same as in the app and in the panel.
- A point type with a symbol set draws its points with an icon instead of a dot. The icon side is the symbol size in meters on the ground, so the icon grows and shrinks with the map scale; it turns according to the object's azimuth (chapter 14). The Layers panel shows the same icon next to such a layer.
- A layer is created only for a type that has objects. When a type loses its last object (deletion or a change of type), its layer disappears.
- The organization's default types are named "Points (default)", "Lines (default)" and "Areas (default)".
- The same type name used for different geometries gets a suffix, e.g. "Hydrants (points)".
The objects of all users of the organization in the active project are loaded. Other people's objects are available for viewing only (chapter 19).
The geoGPS layers are managed by the plugin and are read-only in QGIS — they cannot be changed with the attribute table or the QGIS vertex tool. Make changes to objects with the plugin's tools (object editing, including X/Y/H coordinates, and changing geometry) — only they save the data on the server.
After an object is saved, added or deleted, the plugin updates only what has changed: the other layers are not reloaded.
The "Object photos" layer
On top of the project group there is the Object photos layer — the same as on the map in the web panel. A purple camera marker stands where each photo of the active project's objects was taken. Photos without a saved position have no marker.
- The layer is loaded together with the project. Turn it on and off with its checkbox in the Layers panel.
- Photo preview: click Edit object and then the marker (chapter 11).
- After a photo is added, deleted or changed in the object window, the layer refreshes by itself when that window is closed.
8. Object labels on the map
The Label objects icon opens a window with tiles — clicking a tile selects the option immediately:
| Option | What it shows |
|---|---|
| No label | Objects without labels. |
| Object name | The object name (the default setting). |
| Elevation | The height of the measured point. Lines, areas and points without a height show "NULL". |
| Other parameter | The value of a chosen attribute. After choosing it, enter the Parameter key. An object without this attribute shows "NULL". |
The choice takes effect immediately on all geoGPS layers and is remembered. The selected option has an orange frame and a ✓ mark.
The labels look the same as in the mobile app: points — red, below the point; lines — navy blue, along the line; areas — orange, in the center; all with a white outline. The size comes from the object type, and when it is not set there, it is 20.
Part III – Working with objects
9. Adding a new object
A new object is added to the active project.
- Click New point, New line or New area. The cursor changes into an orange cross, and a hint bar with the Finish and Cancel buttons appears at the bottom of the map.
- Pick the geometry:
- point — a single click on the map,
- line — click successive vertices, at least 2,
- area — click successive vertices, at least 3; the area closes by itself.
A line and an area are finished with the Finish button or a double click. Esc or Cancel stops drawing.
- If you click within 18 pixels of another geoGPS object, the question "Snap to object?" appears:
- Object — the point lands exactly on the existing object,
- Coordinates — the exact clicked place is kept.
- In the New point / New line / New area window fill in:
- Object type,
- Name (required),
- Description,
- Object attributes — any number of key–value pairs.
- Click Save object.
If saving fails, the error is shown in the window, which stays open — you can correct the data and try again.
Geometric data is saved for every vertex: B/L and X/Y in the coordinate system of the active project, with the status "Manual (map pick)". After saving, the layer of the given type is reloaded from the server in full; if it was not present in QGIS, it is created.
10. Editing an object
The edit window can be opened in two ways:
- click Edit object and then an object on the map,
- in the Objects window click the icon next to an object or double-click its row.
The Edit object window has the same layout as editing in the web panel:
| Part | Contents |
|---|---|
| Object type | A list of types with the same geometry type. Changing the type moves the object to another layer. |
| Name, Description | The basic object data. |
| Geometric data | X / Y / H fields for editing coordinates (see below) and a table with the measurements of each point — read-only. |
| Object attributes | Key/Value rows. "+ Add attribute" adds a row, "Delete" removes it. Yes/no values and numbers are stored as boolean and numeric types. |
| Photos | Thumbnails and adding photos (chapter 11). |
| Information | GUID, creation date, last update date. |
Buttons:
- Save — saves the form changes, including changed X/Y/H coordinates and deleted vertices.
- Cancel — closes the window without saving.
- Show on map — zooms the QGIS map to the object.
- Export — saves this object to a file, in the formats from chapter 16. Unsaved changes do not go into the file.
- Change geometry — editing the position on the map (chapter 12).
- Delete — permanently deletes the object from the database together with its photos.
Another user's object
Another user's object opens in the View object window: the fields are locked, and there is Close instead of Cancel. There are no Save, Change geometry or Delete buttons. Show on map and Export remain available.
Editing X/Y/H coordinates
At the top of the Geometric data part there are fields for entering coordinates — one row for a point, and for a line or an area one Vertex N row per vertex.
- X, Y — in the coordinate system in which the object was saved (usually the project's system); the name of the system is in the column header.
- H — normal height above the project's geoid model (the model name is in the column header). The field is optional; an empty H means no height.
- For lines and areas, the vertex numbers are also shown on the map while the window is open — the same as "Vertex N" in the window.
- Delete next to a vertex of a line or an area marks it for deletion (the vertex number is struck through and the button changes to Restore). The vertex is removed from the object only when you click Save. At least 2 (line) or 3 (area) vertices must remain.
When you click Save, the plugin:
- changes only the vertices in which something was changed — the others keep the receiver's measurement data unchanged,
- for changed X/Y recalculates B/L, moves the vertex and sets the status "Import / manual entry" (horizontal accuracy and PDOP are cleared),
- for an entered H calculates the ellipsoidal height h from the project's geoid model,
- after a change of position or deletion of vertices recalculates the line length or the area.
Invalid values (e.g. letters in X/Y or a point outside the B/L range) block saving — the plugin shows a message and the window stays open.
If someone else changed the same object while you were editing it (e.g. in the mobile app or in the panel), a conflicting changes window appears on saving and asks whether to overwrite those changes with yours. Yes saves your version; No saves nothing — open the object again to see the current data. The same applies to saving geometry (chapter 12).
11. Photos
The Photos part of the object edit window:
- + Add photo — select an image file. The photo is saved as JPEG and downsized to 1600 pixels and about 300 KB.
- Clicking a thumbnail opens a preview. The window title is the object name and the photo number.
- In the preview: download, rotate 90°, delete, previous / next, plus a description field with the Save description button.
- Photos of another user's object can only be viewed and downloaded.
Photo changes are saved immediately, independently of the "Save" button in the object window. After the object window is closed (also with Cancel), the Object photos layer refreshes by itself.
Photos on the map
A photo can also be opened from the map, from the Object photos layer (chapter 7):
- Click Edit object and then a photo marker.
- The same preview as in the object window opens. When there are several photos in the clicked place, move between them with the previous / next buttons.
- When an object also lies under the marker, the SELECT OBJECT window appears — choose the object or the Photos: N item.
After a photo is deleted or its description changed, the photos layer refreshes by itself. The number of photos in the organization is limited by the subscription package.
12. Changing geometry
The tool works the same way as "CHANGE GEOMETRY" in the mobile app.
- In the Edit object window click Change geometry. If the form has unsaved changes, the plugin asks whether to save them.
- The map is set on the object (point — a close zoom; line or area — the whole object with a margin). The vertices are shown as blue numbered circles, and the line or the area boundary as a dashed line.
- Edit the geometry:
| Action | How to do it |
|---|---|
| Moving a vertex | Drag the circle to a new place. |
| Snapping to another object | Release the vertex next to another geoGPS object. With a point, its elevation is taken over as well. When there are several objects, choose the right one from the list. |
| Deleting a vertex (line, area) | Click the vertex and choose Delete from the "Point N" menu. At least 2 (line) or 3 (area) must remain. |
| Moving a vertex by picking | Click the vertex, choose Move on map, pick the new place. |
| Inserting a vertex on a side | Click next to a side of the line or area. |
| Adding a vertex at the end | Click elsewhere on the map. |
| Relocating a point | For a point object: click the map in the new place. |
| Panning and zooming the map | Drag in an empty place; the mouse wheel zooms in and out. |
- The bar at the bottom shows the current result: Distance (line), Area (area) or B, L (point).
- Click SAVE, or stop with Cancel / Esc.
Saving sets the new geometry, writes the geometric data of the vertices anew (status "Manual (map pick)", X/Y in the project's coordinate system) and recalculates the length or the area of the object.
13. Object list
The Objects icon opens the list of the active project's objects (of all users of the organization). The window title is the project name.
- Filters: "Object type" and "Name" (searches the name and the description).
- Columns: Name, Object type, Updated at (newest first), Photos, Actions. Clicking a header sorts the list.
- Actions next to an object: the pencil opens editing of your own object, and the eye opens the view of another user's object. Double-clicking a row does the same.
- Checkboxes next to objects select them for export or deletion. The checkbox in the header selects all objects visible after the filters are applied. The selection stays with the object after sorting as well.
- The counter below the table shows the number of objects and of selected objects.
- Refresh list fetches the data again; after editing and deleting, the list refreshes by itself.
Above the table, next to the filters, there are these icons:
- Delete selected — removes the selected objects together with their photos, after confirmation. This cannot be undone. Other people's objects are skipped, and the plugin tells you how many.
- Change type of selected objects (tag icon) — assigns another object type to the selected objects, chosen from a searchable list. The list shows only types matching the geometry of the selected objects, so select objects of one kind (only points, lines or areas). Other people's objects are skipped. After the change the project layers on the map are loaded again.
- Import — chapter 17.
- Export — chapter 16.
- New object — choosing a point, line or area (chapter 9).
14. Tools
The five tools on the geoGPS toolbar are the same tools as in the "Tools" window on the map in the web panel and in the mobile app. Each has its own icon. After clicking it, select an object on the map; Esc ends the tool. When there are several objects in the clicked place, choose the right one from the list.
| Tool | You select | Result |
|---|---|---|
| Rotate symbol | a point with a symbol | changed azimuth of that point |
| Average | successive points | a new point |
| Offset (parallel line) | a line | a new line |
| Extend line | a line, closer to the end to extend | the changed line or its copy |
| Perpendicular segment | a place on a line | a new two-point line |
New objects go to the active project and get the same object type as the selected object. Values in meters can be typed with a comma or a dot.
Rotate symbol
It works only for your own points whose object type has a symbol (chapter 7) — a plain dot has no direction.
- Click Rotate symbol and then a point.
- Set the azimuth in degrees (0° = north, clockwise): with the slider, by typing a value or with the −90°, −5°, +5°, +90° buttons. The symbol on the map turns as you change it.
- Save saves the azimuth on the server, Cancel restores the previous one.
The tool stays on for further points.
Average
- Click Average — the Average of points window opens and stays on screen.
- Click successive points on the map. The window lists them with their measurement status and shows the largest deviation from the average. Undo removes the last point.
- Optionally enter the name of the new point.
- Save (from 2 points) saves the average as a new point.
B, L, heights and precisions are averaged. X/Y and height H go into the result only when all selected points have them in the same system. The measurement status is "RTK fixed" when all points have it, otherwise "Average".
The Delete the selected points checkbox deletes the source points from the database after saving, without a further question — this cannot be undone. You can delete only your own points. Other people's points stay, and the plugin reports how many were not deleted.
Offset (parallel line)
- Click Offset and then a line.
- Enter the Left/right [m] shift and choose the side — relative to the line direction, from the first to the last point. The side you clicked on is selected by default.
- Optionally enter the Up/down - height H [m] shift. The field is available only for a line that has H heights.
- Save — the shifted copy is saved as a new object; the original stays unchanged.
You can enter one value or both. The copy gets the attributes of the original and a name with a suffix, e.g. "Axis (offset 2.00 m)".
Extend line
- Click Extend line and then the line, closer to the end you want to extend.
- Enter the Extension [m] and choose the end: from the start of the line (point 1) or from its end.
- Save — a new point is added on the extension of the end segment.
By default the selected line itself is changed; its existing points keep their measurement data. The Save as a new object (original unchanged) checkbox saves a copy instead. Another user's line can be extended only this way — the server rejects a change to the original.
Perpendicular segment
- Click Perpendicular segment and then the place on the line where the segment should start.
- Check the Distance from the start of the line [m] — the distance of the clicked place is filled in; the window also shows the line length.
- Enter the Segment length [m] and choose the side (left/right relative to the line direction).
- Save — the segment is saved as a new line.
15. Coordinates and measurements on the map
Three measurement tools on the geoGPS toolbar work after signing in and save nothing on the server.
| Tool | What it does |
|---|---|
| Coordinates | Click a place on the map — the WGS84 geographic coordinates are copied to the clipboard and shown on the map. When the QGIS map uses a projected coordinate system, the hint bar also gives X/Y in that system. |
| Measure distance | Click successive points — the result (in meters, from 1000 m in kilometers) is updated as you go. |
| Measure area | Click successive vertices — the result (in m², from 1 ha in hectares) is updated as you go. |
- Clicking close to a geoGPS object snaps the point to it — an orange circle indicates this.
- Undo (also the right mouse button, Backspace or Delete) removes the last point.
- Finish, the Esc key or clicking the tool icon again ends the measurement.
Part IV – Data exchange
16. Exporting objects
- In the Objects window select objects and click Export.
- Choose a format:
| Format | Contents |
|---|---|
| GeoJSON | Full object data. When the objects have photos, a ZIP with the dane.geojson file and the photos is created automatically. |
| CSV | Objects listed vertex by vertex. |
| TXT (survey points) | Points only. |
| KML | For Google Earth and other GIS software. |
| DXF (CAD) | A drawing for CAD software. |
- Choose where to save the file. The suggested file name is
<project>_<date>.
X/Y coordinates are saved in the coordinate system of the active project. Up to 5000 objects can be exported at a time. A ZIP file holds at most 300 photos — export smaller batches when there are more.
A single object can also be exported from its window (chapter 10).
17. Importing objects
- In the Objects window click Import.
- Choose a format and a file:
- GeoJSON — a single file or a ZIP with photos,
- CSV / TXT (survey points) — points; X/Y coordinates in the project's coordinate system, or B/L,
- KML.
- Confirm the import.
Rules:
- The objects are added to the active project.
- Limits of a single import (the same as in the panel): 300 objects, file up to 5 MB, ZIP up to 30 MB.
- Imported vertices get geometric data with the status "Import / manual entry".
- If the file contains a height, the plugin also calculates the ellipsoidal height from the project's geoid model. The model grid is downloaded from
cdn.proj.org, so an import with heights requires Internet access.
Part V – Other
18. Information and logging out
Information shows: the plugin version, the user status (signed in or logged out, login, active project), a description of the geoGPS system, data sources and licenses, and links to the Privacy Policy and the Terms of Service.
Log out removes the access token and all geoGPS layers from the QGIS project. The data on the server remains unchanged. Always log out when other people use the computer.
19. Permissions
The plugin applies the same permissions as the mobile app and the web panel:
- Employees and Managers see the projects and objects of everyone in the organization; other people's data can be viewed, but not edited or deleted.
- A Manager takes over all of an Employee's data after deleting that Employee's account.
- You can edit and delete only your own objects.
- Object types, accounts and the subscription are handled in the mobile app or in the panel.
20. Troubleshooting
| Symptom | What to do |
|---|---|
| No geoGPS toolbar after installation | Check that the plugin is enabled in "Manage and Install Plugins"; restart QGIS. |
| The old version still runs after an update | Delete the geogps_api_qgis folder from the QGIS profile, install the ZIP again and restart QGIS. |
| The icons are greyed out | Sign in; for the object icons, also choose the active project in "Projects". |
| The login code does not arrive | Check your e-mail (including spam) and the geoGPS app notifications; use "Resend code". |
| "Sign in again" | The session has expired — click OK and sign in once more. |
| No access to the data | The organization has no active subscription, or the current Terms of Service have not been accepted. |
| The project is loaded but the map is empty | The project has no objects or has the "blocked" status. |
| A geoGPS layer cannot be edited with QGIS tools | The layers are read-only — use Edit object (including the X/Y/H fields) and Change geometry. |
| The "conflicting changes" window on saving | Someone else changed the object in the meantime — choose whether to overwrite their changes. |
| The plugin is in the wrong language | Change it in Plugins → geoGPS → Język / Language and restart QGIS. |
| No layer for an object type | A layer is created only once the type has at least one object. |
| Photo markers cover the objects | Turn off the Object photos layer in the Layers panel. |
| A photo has no marker on the map | The photo has no saved position. A photo added other than in the object window (e.g. in the mobile app) appears after the project is loaded again. |
| "This point has no symbol to rotate." | The object type of this point has no symbol set — only points with a symbol can be rotated. |
| A tool does not react to clicking an object | Average and Rotate symbol work only for points, the other tools only for lines. |
| The object window has no Save button | It is another user's object — available for viewing only. |
| A line cannot be extended | Another user's line can be extended only as a new object: tick Save as a new object (original unchanged). |
| "Average saved, but some points could not be deleted" | The average is saved. The points were not deleted, most often because they belong to other users. |
| Import rejected | Check the format and the limits: 300 objects, 5 MB, ZIP 30 MB. |
| The import does not calculate heights | No Internet access (geoid grid from cdn.proj.org), or the project has no geoid model. |
| Objects in the wrong place | Check the coordinate system of the active project and the coordinate system of the data in the imported file. |
Support: office@geogps.cloud. Documents: Privacy Policy and Terms of Service.