#327 custom photo names (#331)

* custom photo names

* photo names separate page

* fix

* fix

* typo fix

* Update index.md

removed info about doc viewer

Author: alex-cit

src/.vuepress/sidebar/en.js

@@ -57,6 +57,7 @@ module.exports = {
                 '/gis/search_data',
                 '/gis/settingup_background_map',
                 '/gis/setup_themes',
+                '/gis/photo-names/',
                 '/gis/enable_digitising',
                 '/gis/snapping/',
                 '/gis/proj',

src/gis/enable_digitising.md

@@ -1,7 +1,13 @@
 # How to Enable Digitising
 
-1. Open QGIS Desktop with your <MainPlatformName /> Project 
-2. Navigate to the **Data Sources** in the **Project Properties**
+1. Open your <MainPlatformName /> Project in QGIS
+2. Navigate to **Project Properties**
+   ![QGIS Project Properties](./qgis-project-properties.jpg "QGIS Project Properties")
+   
+3. Inspect **Layers Capabilities** in the **Data Sources** tab.
+
+   At least one layer in your project needs to have no check in the **Read-only** column, otherwise it cannot be edited.
+   
    ![QGIS data sources enable digitising](./qgis_digitising.jpg "QGIS data sources enable digitising")
-   You need to have at least one layer without "Read-only" check
-3. **Apply** the changes. Don't forget to save and sync your project!
+   
+4. **Apply** the changes. Don't forget to save and sync your project!

src/gis/features.md

@@ -16,14 +16,6 @@ In [Creating a Project in QGIS](../tutorials/creating-a-project-in-qgis/) you wi
 ## Background layers
 Various online and offline maps can be used as background layers for navigation during the field survey. You can find more information in [Background Maps](./settingup_background_map/).
 
-## Project extent
-In <MobileAppName />, there is an option to [zoom to the project extent](../field/input_ui/#zoom-to-project-browse-features-map-themes-settings).
-
-To set the project extent, navigate to **Project** > **Properties**. Select **View Settings** and check the **Set Project Full Extent** option. Here, either enter the coordinate extent of your project bounding box or use the map canvas extent.
-
-![QGIS set project extent](./qgis-project-extent.jpg "QGIS set project extent")
-
-If not set, <MobileAppName /> zooms to all visible layers. This is not particularly convenient when you have a layer with a large/global extent (e.g. Open Street Map).
 
 ## Project settings
 - Ensure the paths are set to *Relative* in the **General** tab in Project Properties. All paths to the project data in <MobileAppName /> are relative to the project location.
@@ -35,8 +27,23 @@ If not set, <MobileAppName /> zooms to all visible layers. This is not particula
 
 ![QGIS Layer Capabilities](./qgis_project_properties.jpg "QGIS Layer Capabilities")
 
-### Map themes
-[Map Themes](./setup_themes/) make possible to switch between different background maps in <MobileAppName /> (e.g. cartography maps and aerial imagery)
+### Project extent
+In <MobileAppName />, there is an option to [zoom to the project extent](../field/input_ui/#zoom-to-project-browse-features-map-themes-settings). 
+
+If the project extent is not set, <MobileAppName /> zooms to all visible layers. This is not particularly convenient when you have a layer with a large/global extent (e.g. Open Street Map).
+
+To set the project extent:
+1. Navigate to **Project** > **Properties**. 
+   ![QGIS Project Properties](./qgis-project-properties.jpg "QGIS Project Properties")
+
+2. Select **View Settings** and check the **Set Project Full Extent** option. 
+
+   Here, either enter the coordinate extent of your project bounding box or use the map canvas extent. The extent can be also calculated from a layer in your project.
+
+   ![QGIS set project extent](./qgis-project-extent.jpg "QGIS set project extent")
+
+3. Click **Apply** to save the changes
+
 
 ### Photo quality
 <SinceBadge type="Plugin" version="2022.3.2" /><SinceBadge type="App" version="1.5.1" />
@@ -48,6 +55,17 @@ Don't forget to save and sync your project!
 
 ![Mergin Maps set photo quality](./project_resize_pics.jpg "Mergin Maps set photo quality")
 
+### Photo names
+<SinceBadge type="Plugin" version="2023.2.0" /> <SinceBadge type="App" version="v2.2.0" />
+
+Names of the photos that are captured in the field using <MobileAppName /> can be customised. The name format can be set in QGIS with <QGISPluginName />.  
+
+::: tip
+[How to Set Photo Names Format](../gis/photo-names/) will guide you through the setup and provide examples of expressions that can be used to name your photos.
+:::
+
+![Mergin Maps Plugin photo name setup with custom folder](./plugin-photo-name-settings.jpg "Mergin Maps Plugin photo name setup with custom folder")
+
 ### Snapping
 <SinceBadge type="Plugin" version="2022.5" /><SinceBadge type="App" version="1.6.0" />
 If you want to use snapping in <MobileAppName /> during the field survey, you need to set it up in the **<MainPlatformName />** tab in **Project properties**.
@@ -62,6 +80,9 @@ The snapping options are:
 [How to Set Up Snapping for <MobileAppName />](./snapping/) contains detailed steps that may help you with the snapping setup.
 :::
 
+### Map themes
+[Map Themes](./setup_themes/) make possible to switch between different background maps in <MobileAppName /> (e.g. cartography maps and aerial imagery)
+
 ## Survey layers
 Vector layers can be used as survey layers in <MobileAppName />. You can apply styles and set up the forms to make your field survey easier.
 

src/gis/photo-names/index.md

@@ -0,0 +1,85 @@
+# How to Set Photo Names Format
+<SinceBadge type="Plugin" version="2023.2.0" /> <SinceBadge type="App" version="v2.2.0" />
+
+[[toc]]
+
+Names of the photos that are captured in the field using <MobileAppName /> can be customised. The name format can be set in QGIS with <QGISPluginName />. 
+
+To use this option, make sure that the [photo widget](../../layer/settingup_forms_photo/#attachment-widget-in-qgis) of the fields you use for taking pictures is set up correctly, i.e. using the attachment widget, storing relative paths and, if needed, with a [custom folder](../../layer/settingup_forms_photo/#how-to-set-up-a-custom-folder-for-storing-photos) for storing photos. 
+
+To set up custom photo names:
+1. Open your <MainPlatformNameLink /> project in QGIS and navigate to **Project Properties**
+   ![QGIS Project Properties](../qgis-project-properties.jpg "QGIS Project Properties")
+
+2. In the **Mergin Maps** tab, you can see the list of layers and their fields with correctly configured photo attachment widgets.
+
+   Select a layer from the list and click on the **Expression builder** icon.
+   ![Mergin Maps Plugin Custom photo name setup](./plugin-photo-name-available-layers.jpg "Mergin Maps Plugin Custom photo name setup")
+ 
+3. In the **Expression Dialog** window, enter the expression that should be used as the photo's name. Please, keep in mind [basic recommendations](#best-practice-for-photo-name-expressions) to make sure the naming works as intended.
+
+   Here we use a combination of the layer's name, <MainPlatformName /> username and current timestamp (other examples ale listed [below](#examples-of-photo-names-expressions)): 
+   ` @layer_name + '-' +  @mergin_username + '-' + format_date(now(),'yyMMddhhmmss')`
+   
+   Example result is displayed in the **Preview**: `hedges-sarah-230707194052`
+   
+   ![QGIS Expression for custom photo name](./plugin-photo-name-expression-builder.jpg "QGIS Expression for custom photo name")
+   
+   Click **OK** to confirm the expression.
+
+4. Set up the photo name format for other fields and layers. 
+
+   The **Preview** in **Mergin Maps** tab includes the [custom folder for photos](../../layer/settingup_forms_photo/#how-to-set-up-a-custom-folder-for-storing-photos), if you have set it up. Otherwise you will see only the sample name of a photo.
+  
+   ![Mergin Maps Plugin photo name setup with custom folder](./plugin-photo-name-format-folder.jpg "Mergin Maps Plugin photo name setup with custom folder")  
+   ![Mergin Maps Plugin Custom photo name setup without custom folder](./plugin-photo-name-format.jpg "Mergin Maps Plugin Custom photo name setup without custom folder")
+
+### Best practice for photo name expressions
+There are some tips to keep in mind when creating the expression for your photo name:
+
+:white_check_mark: **Each photo needs to have a unique name** to avoid issues during synchronisation and ensure that photos and features are linked correctly.
+
+Therefore, we recommend using combinations of variables that will ensure that there would not be multiple photos with the same name, such as the current date and time `now()`, <MainPlatformName /> username `@mergin_username`, layer name `@layer_name` or a field value.
+
+:white_check_mark: The file extension (`.jpg`) is added automatically.
+
+:white_check_mark: When using a field value in the expression, make sure that it is a field that will be filled out during the survey, e.g. by using [constraints](../../layer/settingup_forms_settings/#constraints). If the field is empty, the expression won't work!
+
+:white_check_mark: If you want to use a [numeric field](../../layer/settingup_forms/#numbers) or other non-text fields in your expression, you need to convert it to a string first using the `to_string()` function
+
+:no_entry_sign: The expression is evaluated with the **current** field values. The name of the photo will stay the same even if you change the value of the field later.
+
+:no_entry_sign: The setup needs to be saved and synchronised. Only photos that are taken after synchronisation will have the name defined by the expressions. Existing photos will keep their original names.
+   
+In general, it is useful to use some of these variables:
+- Current timestamp `now()` is a good starting point to ensure uniqueness of the name of the photo. 
+
+  It can be variously reformatted using the `format_date()` function. See <QGISHelp ver="latest" link="/user_manual/expressions/functions_list.html#format-date" text="See QGIS User manual" /> for more details.
+  
+- When working in a team, consider using <MainPlatformName /> username `@mergin_username`.
+  
+  Even if multiple team members capture a photo at the same time, the name will be different. Also, it makes it easy to sort photos based on who took them. 
+
+- Layer name `@layer_name` or a field value.
+  
+  Depending on the layers in your project and their fields, it can help create a unique photo name when taking multiple pictures in a row. It can also help to make it easier to browse pictures in your <MainPlatformNameLink /> project.
+
+
+### Examples of photo names expressions
+Here are some example expressions that can be used or modified to fit your needs:
+
+- Expression: ` @layer_name + '-' +  @mergin_username + '-' + format_date(now(),'yyMMddhhmmss')`
+   - Preview: `hedges-sarah-230707154052.jpg`
+   - Description: This is a combination of the name of a layer (`hedges`), <MainPlatformName /> username (`sarah`) and reformatted timestamp that starts with the year and ends with seconds.
+
+- Expression: ` "species" +  format_date( now(),'-yyyyMMdd-hhmmss')`
+   - Preview: `Silver birch-20230707-154052.jpg`
+   - Description: `Silver birch` is a value of the `species` field. Current timestamp is reformatted with added hyphens to separate the date and time.
+
+- Expression: `'photo-' +  format_date( now(),'ssmmhhddMMyy')`
+   - Preview: `photo-520415070723.jpg`
+   - Description: A string can be added to the photo name (here: `photo-`). The order of the timestamp is reversed (compared to the previous examples), starting from seconds.
+
+- Expression: `@layer_name + ' ' + to_string("house-number") + ' at ' + format_date( now(),'ssmmhh') + ' on '+ format_date( now(),'ddMMyy')`
+   - Preview: `house 41 at 520415 on 070723.jpg`
+   - Description: Here we use the name of a layer (`house`), followed by a string adding space. A numeric field (`house-number`) is converted to a string. The timestamp is divided to display the time and date separately, with added strings `at` and `on` to make the photo name more readable.

src/gis/photo-names/plugin-photo-name-available-layers.jpg

@@ -57,6 +57,7 @@ The ecosystem consist of various components:
 - [Searching for Values in Attribute Fields](./gis/search_data/)
 - [Background Maps](./gis/settingup_background_map/)
 - [Map Themes](./gis/setup_themes/)
+- [How to Set Photo Names Format](./gis/photo-names/)
 - [How to Enable Digitising](./gis/enable_digitising/)
 - [How to Set Up Snapping for <MobileAppName />](./gis/snapping/)
 - [Custom Projections](./gis/proj/)

src/gis/photo-names/plugin-photo-name-available-layers.xcf

@@ -60,9 +60,15 @@ To set up a custom folder:
 
 8. **Apply the changes**. Don't forget to save and sync your project!
 
-
 ## Resizing pictures automatically
-Photos that are captured during the field survey or uploaded using <MobileAppName /> can be automatically resized, e.g. to save up storage space. The quality of the photos can be set up in the [Mergin Maps project properties](../gis/features/#photo-quality) using <QGISPluginName />.
+Photos that are captured during the field survey or uploaded using <MobileAppName /> can be automatically resized, e.g. to save up storage space. The quality of the photos can be set up in the [<MainPlatformName /> project properties](../gis/features/#photo-quality) using <QGISPluginName />.
+
+## Customising photo name format with expressions
+Photos taken in the field using <MobileAppName /> can be automatically renamed. This can be useful when browsing pictures in your <MainPlatformNameLink /> project and keeping them organised.
+
+::: tip
+[How to Set Photo Names Format](../gis/photo-names/) will guide you through the setup and provide examples of expressions that can be used to name your photos.
+:::
 
 ## Photos in Mergin Maps Input
 Using the photo widget in <MobileAppName />, you will have two options: