diff --git a/src/.vitepress/sidebar/en.js b/src/.vitepress/sidebar/en.js index 6b3817e7..8e193570 100644 --- a/src/.vitepress/sidebar/en.js +++ b/src/.vitepress/sidebar/en.js @@ -70,7 +70,7 @@ export default { { text: 'Numbers', link: '/layer/numbers/' }, { text: 'Checkbox', link: '/layer/checkbox/' }, { text: 'QR Code', link: '/layer/qr-code/' }, - { text: 'Selecting Single or Multiple Values', link: '/layer/value-select/' }, + { text: 'Selecting a Single or Multiple Values', link: '/layer/value-select/' }, { text: 'Photos', link: '/layer/photos/' }, { text: 'Informational Widgets', link: '/layer/info-widgets/' }, ] }, diff --git a/src/gis/features/index.md b/src/gis/features/index.md index 5a62f7e9..b10b1aec 100644 --- a/src/gis/features/index.md +++ b/src/gis/features/index.md @@ -19,7 +19,7 @@ In [Creating a Project in QGIS](../../tutorials/creating-a-project-in-qgis/) you ## Survey layers Vector layers can be used as survey layers in your project. You can apply styles and set up the forms to make your field survey easier. -The same applies for non-spatial layers that can be used on their own to add new data or linked to a spatial layer, e.g. when linking multiple [photos](../../layer/photos/#how-to-attach-multiple-photos-to-features) or [records](../../layer/one-to-n-relations/). They can be also used in [value relation](../../layer/value-select/#value-relation) widgets. +The same applies for non-spatial layers that can be used on their own to add new data or linked to a spatial layer, e.g. when linking multiple [photos](../../layer/photos/#how-to-attach-multiple-photos-to-one-feature) or [records](../../layer/one-to-n-relations/). They can be also used in [value relation](../../layer/value-select/#value-relation) widgets. Making changes in the data schema of layers can lead to issues in the synchronisation process. Be careful to [**deploy the revised project properly**](../../manage/deploy-new-project/). Design the data schema carefully when creating a layer to avoid the need to change it later. diff --git a/src/layer/form-widgets/index.md b/src/layer/form-widgets/index.md index 229de1f5..3a717db2 100644 --- a/src/layer/form-widgets/index.md +++ b/src/layer/form-widgets/index.md @@ -36,5 +36,5 @@ Here is an overview of widgets that are commonly used both in QGIS and the offers Text and HTML widgets that can be used for this purpose. Your text instructions can include [expressions and field values](#using-expressions-in-text-and-html-widgets) as well. The HTML widget supports various [HTML tags](https://doc.qt.io/qt-6/richtext-html-subset.html#supported-tags), so it can be also used, for instance, to display [online images](#using-html-widget-to-display-online-images-and-other-online-resources). + also offers widgets that can be added to the form to display values or text, but are not connected to a specific field of the layer. supports the HTML, Text and [Spacer](../form-layout/#spacer-widget) widget. + +HTML and Text widgets can be used, e.g., to [display instructions](#text-and-html-widget) in the form. The HTML widget supports various [HTML tags](https://doc.qt.io/qt-6/richtext-html-subset.html#supported-tags), so it can be also used, for instance, to display [online images](#using-html-widget-to-display-online-images-and-other-online-resources) or [open local files](#using-html-widget-to-open-local-files). + +|
Widget
|Preview in the | +|:---:|:---:| +[Text and HTML Widgets](#text-and-html-widget) | ![Mergin Maps mobile app HTML and Text widgets in attributes form](../form-widgets/mobile-form-info-widgets.webp "Mergin Maps mobile app HTML and Text widgets in attributes form") | + + +## Text and HTML widget +The **Text** and **HTML widgets** provide an option to include instructions or tips for surveyors in your attributes forms. These text instructions can include [expressions and field values](#using-expressions-in-text-and-html-widgets) as well. These widgets can be found in **Available Widgets** in the **Other Widgets** section when using the [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer). ![QGIS HTML and Text Widget](./qgis-form-html-text-widget.jpg "QGIS HTML and Text Widget") @@ -16,15 +25,15 @@ If you prefer your text to be formatted, you may do so in the **HTML** widget. H ...and this is how the Text and HTML widgets look like in the form in QGIS (left) and in the mobile app (right). ![Text and HTML widgets in QGIS and in Mergin Maps mobile app](./qgis-form-text-html.jpg "Text and HTML widgets in QGIS and in Mergin Maps mobile app") -## Using expressions in Text and HTML widgets +### Using expressions in Text and HTML widgets Expressions and variables can be used both in the Text and the HTML widget. -![QGIS Configure Text Widget Expression Builder](./qgis-text-widget-expression.gif "QGIS Configure Text Widget Expression Builder") - -:::tip +:::tip Example project available Clone to follow this example. ::: +![QGIS Configure Text Widget Expression Builder](./qgis-text-widget-expression.gif "QGIS Configure Text Widget Expression Builder") + 1. When configuring the Text or HTML widget, click on the **Expression Builder** button 2. Enter the expression that will be used in your text and click **OK**. @@ -33,6 +42,7 @@ Clone to follow this examp 3. Click on the **+** button to add the expression to the text. Here, we configured the widget with this text: + `Make sure the number plate [% "VRP" %] is visible in the photo.` In this case, `VRP` is the name of a field aliased as `Vehicle Registration Plate` in the form. @@ -42,7 +52,7 @@ Clone to follow this examp ... and this is how it works during the field survey. `[% "VRP" %]` expression displays the current value of the `Vehicle Registration Plate` field. ![Mergin Maps mobile app text widget with variable](./mobile-text-widget-expression.jpg "Mergin Maps mobile app text widget with variable") -## Using HTML widget to display online images and other online resources +## Display online images and other online resources using HTML widget {#using-html-widget-to-display-online-images-and-other-online-resources} The **HTML widget** can be also used to display online images in the mobile app or open online resources, such as PDF files, videos or websites, in the browser of your device. ::: tip @@ -73,7 +83,7 @@ QGIS may not display the preview of the online image if you use QGIS 3.36 or hig ::: -## Using HTML widget to open local files +## Open local files using HTML widget {#using-html-widget-to-open-local-files} The HTML widget can also be used to open local files: for instance, a locally stored PDF file can be opened from within the form during the survey. ::: tip @@ -97,16 +107,3 @@ Local files can be displayed in the form also using [default values](../open-fil In the project, you can explore and compare both alternatives. ::: - -## Spacer widget - -The Spacer widget can be useful if you want to have some space between the fields in your form or add a horizontal line. - -It can be found in *Available Widgets* in the *Other Widgets* section when using the [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer). -![QGIS forms Spacer Widget](./qgis-form-spacer-widget.jpg "QGIS Spacer Widget") - -When adding the spacer widget to the form, there is an option to check the **Draw horizontal line** option. Otherwise, a vertical space will be added to the form. -![QGIS Spacer Widget configuration](./qgis-configure-spacer-widget.jpg "QGIS Spacer Widget configuration") - -And this how the spacer widget looks like in the form in QGIS (left) and in the mobile app (right). -![Spacer widget in QGIS and mobile app form](./spacer-widget-forms.jpg "Spacer widget in QGIS and mobile app form") diff --git a/src/layer/photos/index.md b/src/layer/photos/index.md index 0bbd2ced..f74ea6d4 100644 --- a/src/layer/photos/index.md +++ b/src/layer/photos/index.md @@ -1,24 +1,27 @@ +--- +outline: deep +--- + # Photos [[toc]] -When surveying, you might want to take a photo from your camera or attach an existing photo from the device gallery to your survey feature. +Adding photos to a surveyed feature can be really helpful. With , you can quickly take photos during the survey, share them with your team and store them in the cloud. You can either capture a photo using your camera or select existing photos from the gallery. -To capture and save photos using the , the survey layer needs to have a field configured with the [**Attachment** widget](#photo-attachment-widget-in-qgis) in QGIS. + offers some useful functionalities for capturing photos: +- More than one photo can be attached to one feature. Follow our guide [How to attach multiple photos to features](#how-to-attach-multiple-photos-to-one-feature) to do so. +- Photos can be named automatically based on a [customised names format](#customising-photo-name-format-with-expressions). +- Synchronising photos during the field survey can use up a lot of mobile data, depending on the amount of pictures taken and their size. To reduce the data usage, you may use [selective synchronisation](../../manage/selective_sync/), [resizing pictures automatically](../../gis/features/#photo-quality) or following the [offline field survey workflow](../../field/offline-use/#offline-field-survey-workflow). -In the , this field will provide two options: -- **Take a picture** to use your camera app for taking a photos -- **From gallery** to attach an existing photo from your device - -![Mergin Maps mobile app photo widget](./mobile-form-attachment-photo.jpg "Mergin Maps mobile app photo widget") +|
Widget
|Preview in the | +|:---:|:---:| +[Attachment - Photos from device's camera or gallery](#photo-attachment-widget-in-qgis) | ![Mergin Maps mobile app attachment field form](../form-widgets/mobile-form-photo-preview.jpg "Mergin Maps mobile app attachment field form") ![Mergin Maps mobile app attachment field form](../form-widgets/mobile-form-photo-preview2.jpg "Mergin Maps mobile app attachment field form") | +|[Relation - Gallery ](#how-to-attach-multiple-photos-to-one-feature) | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | -:::tip -Do you need to attach multiple pictures to one feature? [How to attach multiple photos to features](#how-to-attach-multiple-photos-to-features) will guide you through the setup. -::: -::: warning -Keep in mind that synchronising photos during the field survey can use up a lot of mobile data - depending on the amount of pictures taken and their size. +:::tip Example projects available +To see the basic [attachment widget](#photo-attachment-widget-in-qgis) setup for photos, clone . -To reduce the data usage, you may consider using [selective synchronisation](../../manage/selective_sync/), [resizing pictures automatically](../../gis/features/#photo-quality) or following the [offline field survey workflow](../../field/offline-use/#offline-field-survey-workflow). +If you want to [attach multiple photos to one feature](#how-to-attach-multiple-photos-to-one-feature) explore the public project . ::: ## Photo attachment widget in QGIS @@ -27,7 +30,7 @@ To reduce the data usage, you may consider using [selective synchronisation](../ Clone to follow this example! ::: -In QGIS, the **Attachment** widget is used to set up a field to capture photos. +To add photos to features using the , the attributes form of a survey layer needs to have a field with data type `Text (string)` configured with the **Attachment** widget in QGIS as follows: To set up the attachment widget: 1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. @@ -36,22 +39,32 @@ To set up the attachment widget: - From the drop-down menu, select **Attachment** - **Default path** defines where images will be saved. If it is not defined, the project home folder will be used. - Store the path as **Relative to project path** or **Relative to default path** depending on how you want to store the paths. + + ![QGIS photo attachment widget form](./qgis_form_photo.webp "QGIS photo attachment widget form") + + :::danger Avoid using absolute paths + Using *absolute paths* causes issues when working with your projects on different devices or working in a team: as each device or team member can use different paths, they may be unable to display the images. + ::: + 4. **Apply** the changes. Don't forget to save and sync your project! -![QGIS photo attachment widget form](./qgis_forms_photo.jpg "QGIS photo attachment widget form") -:::danger Avoid using absolute paths -Using *absolute paths* causes issues when working with your projects on different devices or working in a team: as each device or team member can use different paths, they may be unable to display the attachments. -::: +In the , this field will provide two options: +- **Take a picture** to use your camera app for taking a photos +- **From gallery** to attach an existing photo from your device + +![Mergin Maps mobile app photo widget](./mobile-form-attachment-photo.jpg "Mergin Maps mobile app photo widget") -### How to set up a custom folder for storing photos +## Custom folder for storing photos {#how-to-set-up-a-custom-folder-for-storing-photos} It can be useful to set up a custom folder for photos, e.g. if you want to use [selective synchronisation](../../manage/selective_sync/) or if you simply want to have your data organised. To set up a custom folder: 1. Create a subfolder in the project folder (here: `photos`) 2. Open your project in QGIS -3. Open the **Properties** of the survey layer and navigate to the **Attributes form** tab. - Select the field, where photos are stored (here: `photo`) and make sure that the widget type is set to **Attachment**: - ![QGIS photo attachment widget form](./qgis_form_photo.jpg "QGIS photo attachment widget form") +3. Open the **Properties** of the survey layer and navigate to the **Attributes form** tab. + + Select the field, where photos are stored (here: `photo`) and make sure that the widget type is set to [**Attachment**](#photo-attachment-widget-in-qgis) + ![QGIS photo attachment widget form](./qgis_form_photo.webp "QGIS photo attachment widget form") + 5. Now we need to change the **Default path** to the folder we have created. Click on the *Data defined override* icon and choose **Edit...** ![QGIS edit default path expression](./qgis_form_photo_edit_expr.jpg "QGIS edit default path expression") @@ -105,49 +118,61 @@ QGIS may not display the preview of the image if you use QGIS 3.36 or higher. De ::: -## How to Attach Multiple Photos to Features +## How to attach multiple photos to one feature -In some situations, it might be useful to take more than one picture of a feature during the field survey. Attaching multiple photos to one feature is a [one to many relation](../relations). +In some situations, it might be useful to take more than one picture of a feature during the field survey. Attaching multiple photos to one feature is a **one to many relation**. You can read more about this topic in general in [Relations](../relations). |
Widget
|Preview in the | |:---:|:---:| -|[Relation - Gallery ](../photos/#how-to-attach-multiple-photos-to-features) | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | +|Relation - Gallery | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | :::tip Example project available -To see this setup in practice, you can download the following project: -. +To see this setup in practice, you can download this public project . ::: -To link multiple photos to a single feature, we need a **unique UUID field** to link following tables: -- Survey layer containing spatial information -- A non-spatial table containing path to the photos (here: `photos`) +### Non-spatial layer for storing photos +To link multiple photos to a single feature, we need to have a non-spatial layer (table) to store the paths to the photos. + +1. Here we will create a new GeoPackage layer named `photos` with following attributes: + - `photo` with `Text (string)` data type to store the photo path + - `external-pk` with `Text (string)` data type to store the reference to the feature from the survey layer + + ![QGIS creating a non-spatial layer for storing photos](./qgis-create-photos-table.webp "QGIS creating a non-spatial layer for storing photos") + + ::: tip Using default values + You may add other attributes as needed, e.g. to record the username or dates automatically using [default values](../default-values/). + ::: + +2. Now we need to configure the attributes form: set the `photo` field to store photo paths as described in the [photo attachment widget](#photo-attachment-widget-in-qgis). + +### Relation setup +The `photos` layer will be linked to the survey layer using an UUID: the survey layer needs to have a **unique UUID** field generated by the `uuid()` function (see how to set it up [here](../relations/#generating-unique-ids-uuid)) and the [`photos` layer](#non-spatial-layer-for-storing-photos) has a field to store the foreign key (here: `external-pk`). :::danger Use UUIDs to link layers **Do not use the FID field to link these tables**. FIDs can be changed during synchronisation, which can result in having photos linked to the incorrect feature. See [Behind Data Synchronisation](../../manage/synchronisation/) for more details. -Therefore, you should always use unique UUIDs generated by the `uuid()` function to link layers as they do not change during the sync. +You should always use unique UUIDs generated by the `uuid()` function to link layers as they do not change during the sync. ::: -To set 1:N relation between these tables correctly: -1. Create a new text field in the survey layer, here: `unique-id` -2. Use the `uuid()` as the **default value** for this field in **Layer Properties**. This function assigns a unique identifier to every created feature, even when different surveyors create features simultaneously. - ![UUID as default value in Attributes Form](./uuid-default.jpg "UUID as default value in Attributes Form") -3. Create a new text field in the non-spatial table (here: `photos`) that will be used to store the UUID of features from the survey layer (the foreign key), here: `external-pk`. +Navigate to the [**Relations**](../relations/#setting-up-relation-in-qgis) tab in **Project Properties** and **Add Relation** as follows: +- **Name** is the name of the relation, can be left blank +- **Referenced (parent)** is the spatial layer `Survey` +- **Field 1** of the **Referenced (parent)** is the field `unique-id` that contains the UUID +- **Referencing (child)** is the non-spatial layer `photos` +- **Field 1** of the **Referencing (child)** layer is the `external-pk` that contains the foreign key to link photos with surveyed features. + +![Surveyed feature and photos relation setup](./qgis_relation_photos.jpg "Surveyed feature and photos relation setup") + +### Relations widget (gallery) in the form -Now we need to configure a [1-N relation](../relations/): +Check the **Attributes form** tab in the **Layer Properties** of your survey layer and make sure that the [relation widget](../relations/#attributes-forms-configuration-for-1-n-relations) is included in the form. -4. Navigate to the **Relations** tab in **Project Properties** and **Add Relation** as follows: - - **Name** is the name of the relation, can be left blank - - **Referenced (parent)** is the spatial layer `Survey` - - **Field 1** of the **Referenced (parent)** is the field `unique-id` that contains the UUID - - **Referencing (child)** is the non-spatial layer `photos` - - **Field 1** of the **Referencing (child)** layer is the `external-pk` that contains the foreign key to link photos with surveyed features. - ![Surveyed feature and photos relation setup](./qgis_relation_photos.jpg "Surveyed feature and photos relation setup") +If you use [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer), you may need to add it to the form manually. -Check to the **Attributes form** tab in the **Layer Properties** of your survey layer and make sure that the [relation widget](../relations/#attributes-forms-configuration-for-1-n-relations) is included in the form. +![Photo relation widget in QGIS attributes form](./qgis-form-photo-relation.webp "Photo relation widget in QGIS attributes form") -The detects the type of 1-N relation and displays the image viewer for the relations. +The detects the relation widget and allows to add multiple images to one feature, displaying them in a gallery form. ![Many photos to a single feature in Mergin Maps mobile app](./mobile-multiple-photos.jpg "Many photos to a single feature in Mergin Maps mobile app") diff --git a/src/layer/photos/qgis-create-photos-table.webp b/src/layer/photos/qgis-create-photos-table.webp new file mode 100644 index 00000000..ddaec994 Binary files /dev/null and b/src/layer/photos/qgis-create-photos-table.webp differ diff --git a/src/layer/photos/qgis-create-photos-table.xcf b/src/layer/photos/qgis-create-photos-table.xcf new file mode 100644 index 00000000..88aacd71 Binary files /dev/null and b/src/layer/photos/qgis-create-photos-table.xcf differ diff --git a/src/layer/photos/qgis-form-photo-relation.webp b/src/layer/photos/qgis-form-photo-relation.webp new file mode 100644 index 00000000..609fdd5a Binary files /dev/null and b/src/layer/photos/qgis-form-photo-relation.webp differ diff --git a/src/layer/photos/qgis-form-photo-relation.xcf b/src/layer/photos/qgis-form-photo-relation.xcf new file mode 100644 index 00000000..db63fffb Binary files /dev/null and b/src/layer/photos/qgis-form-photo-relation.xcf differ diff --git a/src/layer/photos/qgis_form_photo.jpg b/src/layer/photos/qgis_form_photo.jpg deleted file mode 100644 index e5c26301..00000000 Binary files a/src/layer/photos/qgis_form_photo.jpg and /dev/null differ diff --git a/src/layer/photos/qgis_form_photo.webp b/src/layer/photos/qgis_form_photo.webp new file mode 100644 index 00000000..ffdeecee Binary files /dev/null and b/src/layer/photos/qgis_form_photo.webp differ diff --git a/src/layer/photos/qgis_form_photo.xcf b/src/layer/photos/qgis_form_photo.xcf index b9ec0463..4d9e6815 100644 Binary files a/src/layer/photos/qgis_form_photo.xcf and b/src/layer/photos/qgis_form_photo.xcf differ diff --git a/src/layer/photos/qgis_forms_photo.jpg b/src/layer/photos/qgis_forms_photo.jpg deleted file mode 100644 index 7a81c6e1..00000000 Binary files a/src/layer/photos/qgis_forms_photo.jpg and /dev/null differ diff --git a/src/layer/photos/qgis_forms_photo.xcf b/src/layer/photos/qgis_forms_photo.xcf deleted file mode 100644 index 5958f546..00000000 Binary files a/src/layer/photos/qgis_forms_photo.xcf and /dev/null differ diff --git a/src/layer/relations/index.md b/src/layer/relations/index.md index da73192d..d936d128 100644 --- a/src/layer/relations/index.md +++ b/src/layer/relations/index.md @@ -12,14 +12,14 @@ There are cases when multiple records from one layer (or table) relate to one fe |
Widget
|Preview in the | |:---:|:---:| | [Relation](../one-to-n-relations/) | ![Mergin Maps mobile app relation form](../form-widgets/mobile-form-relations-preview.jpg "Mergin Maps mobile app relation form") | -|[Relation - Gallery ](../photos/#how-to-attach-multiple-photos-to-features) | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | -| [Relation reference](#referencing-child-layer-attributes-form) | ![Mergin Maps mobile app relation reference form](./mobile-form-relation-reference-preview.webp "Mergin Maps mobile app relation reference form") | +|[Relation - Gallery ](../photos/#how-to-attach-multiple-photos-to-one-feature) | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | +| [Relation reference](#referencing-child-layer-attributes-form-relation-reference-widget) | ![Mergin Maps mobile app relation reference form](./mobile-form-relation-reference-preview.webp "Mergin Maps mobile app relation reference form") | :::tip Example projects and guides available You can take a closer look at 1-N relations: - Public project contains the setup described on this page as well as sample data - [How to Link Multiple Records to One Feature](../one-to-n-relations/) explains how to add multiple **records** to a single feature. See also our public project: -- [How to Attach Multiple Photos to Features ](../photos/#how-to-attach-multiple-photos-to-features) shows how to add multiple **photos** to a single feature. See also our public project: +- [How to Attach Multiple Photos to Features ](../photos/#how-to-attach-multiple-photos-to-one-feature) shows how to add multiple **photos** to a single feature. See also our public project: ::: As an example, we will use a project with two spatial layers: **parks** and **amenities**. One park can have multiple amenities, such as benches, picnic tables, fireplaces or water fountains. Every amenity feature can be located in one park only. Thus, the relation between these layers is one to many (1-*N*): 1 park to *N* amenities. diff --git a/src/layer/text/index.md b/src/layer/text/index.md index c5253921..2eed2e77 100644 --- a/src/layer/text/index.md +++ b/src/layer/text/index.md @@ -39,7 +39,7 @@ The **Text Edit** widget offers the option to store multiple lines within a sing In the , the **multiline text edit widget** looks like this: ![Mergin Maps mobile app multiline text field form](./mobile-form-text-multiline.jpg "Mergin Maps mobile app multiline text field form") -## Recording text options +## Voice input In the , the text can be entered manually or using voice-to-text (if your mobile device supports this feature). diff --git a/src/layer/value-select/index.md b/src/layer/value-select/index.md index 2c8ece64..45bf15cb 100644 --- a/src/layer/value-select/index.md +++ b/src/layer/value-select/index.md @@ -1,4 +1,4 @@ -# Select value from a drop-down menu +# Selecting a Single or Multiple Values [[toc]] Selecting values from a drop-down menu is faster than typing them in manually and it also ensures that there are no typos or spelling variations.