Modify
Once uploaded files are processed a user can modify them.
Please see UI mockups for modify pages: UX-005 - Modifying Sequence

Delete single images

User can select one or more images to delete from a Sequence manually.
Sequence must always have >=10 images. If a delete will result in >10 images, they will see a warning and not be able to proceed.
Note, if user select "Delete photo" it will still show in edit mode, but user can click "Undelete" to reinstate it before publishing in case the change their mind.

A note on delete actions

In the database, we do not delete photo records.
A photo is either ACTIVE or INACTIVE. If it is INACTIVE, it is not considered in sequence.
This allows a user to "Reset to original" at any time should they need to.
Aggregated metrics (originally processed during upload processing) should be recalculated to reflect only ACTIVE photos when a modification to a Sequence is saved (e.g. distance to next photo). Until the point of save, modifications to a Sequence are held in application memory.

Add a user defined nadir / watermark

A nadir (for equirectangular) or watermark (for non-equirectangular) in this context refers to a logo at the base of each image.
We add a predefined branded nadir at upload to a copy of the images. This step allows them to remove or change it.
In the case of remove nadir, the image copy with no nadir is used.
In the case of add custom nadir, we allow users to upload their own square .png image to use as a nadir/watermark.
If user uploads image it must be
  • <= 5mb
  • .png
  • square dimensions
  • gt= 500 px height
Nadir is previewed to user before they save it. To do this, the nadir/watermark is overlaid on first image (by time) in Sequence. User is also presented with various size options for nadir for preview, between 12 - 20% in 1% increments.
Processing will retain all original image metadata. Once processing complete all temporary files are then removed from media processing server.
User can try lots of different nadirs (see modify image actions). Therefore, the base images used to generate the nadir should be the raw copy created at upload (the copy created without the Trek View nadir).

Note on nadir / watermark storage

When image modifications made (for add nadir function) we create a new set of ACTIVE and INACTIVE images (all files in raw_DATETIME) with the nadir using the files in the raw directory
Once a nadir have been processed the files are stored in
  • sequences
    • USER_UUID
      • SEQUENCES_UUID
        • raw_DATETIME
        • nadir_DATETIME
          • FILENAME.jpg
Note, a user can add a nadir more than once (for example, if they want to download multiple versions of same sequence with different nadir). Hence, multiple nadir_DATETIME folders can exist. The Nadir file is always created from files in raw_DATETIME directory.

Note on nadir / watermark precedent

User can potentially have many different versions of a Sequence by adding a nadir.
If no nadir version, raw directory on S3 is master image source shown to user.
If nadir version(s), latest nadir version by timestamp on S3 is master image source shown to user.
ACTIVE and INACTIVE images still apply whatever version of the Sequence images is being used.

Reset all modification actions

User also has option to reset all modifications.
In triggering this option, all photos become active and aggregated photo metrics (e.g. distance to next photo), returning to state of sequence at time of upload complete.

PROCESSING state

When any modifications made, Sequence enters processing state until all modification have been completely processed. This stops a user making more modifications to a Sequence immediately after saving it, creating possible corruption.

Delete sequence

User can choose to delete entire sequence in this state. In such a case all images on S3 and metadata removed. Note, they will not be removed from integrations (user should see warning "This action will delete all files held on our server. If you have uploaded to 3rd party platforms, you will also need to delete the images on these platforms manually".

LOCKED state

Once a user is happy with their modifications they can save their sequence as final. At which point it will enter LOCKED state, at which point final processing steps will begin (seq-state-13)

Processing actions

Once user saves their sequence as final, they must authenticate to Mapillary (for upload). Once complete the images go through one final set of processing actions. The following processing steps happen:

1. Authenticate to Mapillary

1. Create final modification images

This step creates a .zip download of final images on S3 of the top precedent active images

1.1 Pre-process for Mapillary

In anticipation of a Mapillary integration, required Mapillary data should be written into the final images.
Mapillary looks for a JSON object in the ImageDescription field to process imagery.
The JSON object inside each image has the following values;
  • explorer_sequence_UUID (string): UUID assigned by Explorer
  • explorer_photo_UUID (strong): UUID assigned by Explorer
  • MAPLongitude (float): Longitude of the image
  • MAPLatitude (float): Latitude of the image
  • MAPAltitude (float): Altitude of the image
  • MAPCaptureTime (string): Capture time in UTC, specified in the format of %Y_%m_%d_%H_%M_%S_%f. For example, the standard time 2019-12-29T10:25:39.898Z should be formatted as 2019_12_29_10_25_39_898.
This is written with exiftool into each image like so:
1
exiftool XMP-tiffImageDescription:"{JSON_OBJECT_BODY_FOR_IMAGE}" FILENAME.jpg
Copied!
An example of a final object in the ImageDescription field will look like this:
1
{
2
"trek_view_explorer_sequence_UUID":"cdc04260-6d8f-4d91-8903-fb79a9197b8a",
3
"trek_view_explorer_photo_UUID":"a092d009-503c-4e19-9dad-63156f4ff573",
4
"MAPAltitude":319.248,"MAPLatitude":28.7151519999722,
5
"MAPLongitude":-13.8921749,
6
"MAPCaptureTime":"2020_08_14_11_43_46_000",
7
}
Copied!

1.2 Save this files

The files should be written into a new final_DATETIME directory, which should also contain a .zip file of all the final images.
  • sequences
    • USER_UUID
      • SEQUENCES_UUID
        • final_DATETIME
          • SEQUENCE_UUID.zip
          • image1.jpg
          • image2.jpg
          • ...

2. Create the sequence mp4

This step creates a video on S3 of the top precedent active images.

2.1 Create video from frames

We should create the video using the same frame rate (-f X)as the images. Depending what files were uploaded there are a couple of variations:
1
$ ffmpeg -start_number 1 -r X -i img_%d.jpg -pix_fmt yuv420p -c:v libx264 SEQUENCE_UUID.mp4
Copied!

2.2 Add camera metadata

In order to ensure video timings are extracted correctly later, we should inject a minimum amount of metadata to the video taken from the first image (by time) user to create the video.
Image metadata value
Image metadata example
New video metadata
Video metadata example
IFD0:Model
GoPro MAX
IFD0:Model
GoPro MAX
SubSecDateTimeOriginal
2021:06:23 16:22:21.222
CreateDate
2021:06:23 16:22:21.222

2.3 Add required spatial metadata (equirectangular sequences only)

New video metadata
Example
XMP-GSpherical:Spherical
true
XMP-GSpherical:Stitched
true
XMP-GSpherical:StitchingSoftware
Spherical Metadata Tool
XMP-GSpherical:ProjectionType
equirectangular

2.4 Save this file

The files should be written into the final_DATETIME directory
  • sequences
    • USER_UUID
      • SEQUENCES_UUID
        • final_DATETIME
          • SEQUENCE_UUID.mp4

3. Create GPX file

3.1 Create the gpx file

GPX (the GPS Exchange Format) is a light-weight XML data format for the interchange of GPS data (waypoints, routes, and tracks).
You can read more in the GPX docs here or the full schema here.
It can be created using the following template:
1
<?xml version="1.0" encoding="UTF-8"?>
2
<gpx
3
version="1.1"
4
creator="Trek View Explorer"
5
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
6
xmlns="http://www.topografix.com/GPX/1/1"
7
xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
8
<trk>
9
<name>SEQUENCE_UUID.GPX</name>
10
<trkseg>
11
<trkpt lat="LAT" lon="LON"><ele>ELE</ele>
12
<time>TIME</time></trkpt>
13
<trkpt lat="LAT" lon="LON"><ele>ELE</ele>
14
<time>TIME</time></trkpt>
15
...
16
</trkseg>
17
</trk>
18
</gpx>
Copied!
The variables printed in the XML are:
GPX variable
Description
Example
LAT
Latitude (in decimal format)
28.689014
LON
Longitude (in decimal format)
-13.931480
ELE
Elevation (in decimal format)
91
TIME
Date / time (Zulu)
2020-08-02T11:05:09Z

3.2 Save this gpx file

The files should be written into the final_DATETIME directory
  • sequences
    • USER_UUID
      • SEQUENCES_UUID
        • final_DATETIME
          • SEQUENCE_UUID.gpx

4. Upload to Mapillary

5. Final processing done

Once all processing steps done (and sequence is marked as published to Mapillary), user can start to
Last modified 3d ago