Skip to content

README.md

Latest commit

 

History

History
333 lines (215 loc) · 21.3 KB

README.md

File metadata and controls

333 lines (215 loc) · 21.3 KB
Raw

GeoELAN v3.0.0 2026-09-06

GeoELAN can be used to annotate action camera GPS logs with the help of the free annotation tool ELAN. Currently supported devices are GoPro Hero Black series or insta360 X-series (X4 and later). See Requirements below.

GeoELAN is multi-functional tool that consists of a command line (CLI) version and a graphical (GUI) version. Functionality currently differs between the two.

Important:

  • GoPro Hero 12 Black does not have a GPS module and is not supported. GoPro Hero 13 Black once again has a GPS and should be compatible.
  • Garmin has discontinued the VIRB Ultra 30. Garmin VIRB support was removed for this version due to lack of time but may return in a later version.

Note: To support more devices, test data is required, and preferrably some description of the telemetry format. Currently supported devices reflect what we have access to and use.

With GeoELAN, you can:

  • geo-reference ELAN-annotations of GoPro and VIRB footage (i.e. annotate GPS logs) and generate annotated points, lines, or circles.
  • CLI: inspect the raw content of your GoPro GPMF data, and formated insta360 data.
  • CLI + GUI: locate and match all relevant files belonging to the same recording session (clips, telemetry-files).
  • CLI + GUI: automatically join clips for a specific recording session, and generate an ELAN-file with linked media (requires FFmpeg).

The geoelan executable contains the full PDF manual for convenience: geoelan manual --pdf.

List available sub-commands with geoelan --help. List parameters for each sub-command with geoelan SUBCOMMAND --help, e.g. geoelan locate --help.

Introduction

GeoELAN is a tool that geo-references time-aligned text-annotations of observed phenomena in audiovisual recordings, captured with a recent GoPro or insta360 action camera, see Larsson et al 2021. In other words, GeoELAN is used for annotating action camera GPS logs with the help of the free annotation tool ELAN.

Requirements:

  • GoPro Hero 5 Black and later, including Mission 1 series. However, Hero12 Black does not have a GPS module and is not supported.
  • insta360 X4, X5 (possiby also X3, and the new X6, but these are untested). X2 and earlier are currently unsupported due to a different file layout.
  • ELAN (documentation)
  • FFmpeg (in PATH preferred, but custom path can also be set when running GeoELAN)
    • Note macOS: For the GUI version, ensure ffmpeg runs before running GeoELAN. No compiled versions of ffmpeg available are notarised. macOS will block ffmpeg if the com.apple.quarantine file attribute is set. The attribute can be removed in the Privacy & Security settings in system settings the first time ffmpeg is run. Alternatively run xattr -r -d com.apple.quarantine PATH/TO/ffmpeg in a terminal. Either of these require admins password.

Geo shape

The term "geo shape" refers to available geometry types for the final output, ranging from points to linestrings.

In general, any logged point with a timestamp that intersects with the timespan of an annotation in the selected ELAN-file will inherit the annotation value as a description.

You can choose between:

  • point: All points will be included, alternating between points with descriptions (intersect with an annotation) and no descriptions.
  • point-marked: Only points that intersect with an ELAN annotation will be included.
  • point-marked-single: Same as point-marked with the difference that each annotation will instead be represented by a single, averaged point. Practical for POI-like data such as place names or plant observations.
  • line: A continuous linestring, alternating between sections with descriptions (intersect with an annotation) and no descriptions.
  • line-marked: A broken-up linestring. Only sections that intersect with an ELAN annotation will be included.

Graphical interface (GUI) version

Install

See releases to the right for pre-compiled binaries for Windows (x86), macOS (Apple Silicon, x86). The macOS binary is universal and notarized, but the Windows version is not. Linux is supported but currently lacks a pre-compiled binary.

There is a short help section in the upper-right of the main window. Better documentation is being worked on but may take a while. The GUI is hopefully a bit more self-explanatory than the command line version.

Map and Plot views

In the upper right you can switch between a map and a plot view. These can not be actived until files have been imported.

The bottom panel

The bottom panel consists of five sub-panels: "Import source files", "Export ELAN file", "Export geo-data", "Export CSV", device and recording session summary. Here is a quick walk-through.

Import source files

Files from compatible devices can be dropped on the main window (MP4, LRV, INSV) or selected via the "Source" under "Import source files" in the lower panel. If you also drop or select a folder it is assumed to be the folder for locating clips for the recording session in question. When you click "Import", files will be located and telemetry will be extracted and merged. Locating files may take a while if the search area is large (e.g. an entire external hard drive). When finished the "Map" view will activate.

You can export raw geo-data as GeoJSON, KML, GPX, and GeoPackage.

Import recording session

Export ELAN file

First, see the FFmpeg note under "Requirements" above. Ensure FFmpeg runs before running GeoELAN, regardless of operating system.

Select ("FFmpeg" button) or drop the FFmpeg execuable onto the window, then select output folder ("Folder").

Exporting a ELAN-file will also join located clips for the recording session, which is why FFmpeg is currently required.

Clicking "Export" will open a window with a few options for what telemetry to include in the ELAN-file. Geo-tier will add a tier with geo-coordinates as annotation values and a time series for altitude. There are also options for including IMU (accelerometer and gyroscope) data, and for GoPro devices data that relate to how well the camera could lock on to satellites. IMU data is downsampled 20 times (originally around 200Hz) and geo-data 10 times (originally around 10Hz), but you can always export the full-resolution data via "Export geo-data" or "Export CSV".

Please note that it may take some time to join the clips. The export is not done until the export status in the export window says "Export succeeded" and there is a new button saying "Show files".

Export ELAN-file

Export geo-data

Export geo-data to GeoJSON, KML, GPX, and GeoPackage. You can either add an ELAN-file and select a tier to apply as a temporal filter in the Map view or export the raw geo data as it was originally logged.

Load an ELAN-file by dropping it or use the "ELAN-file" button. Select a tier, and a geo shape (see the Geo shape section above). When a tier and geo shape is selected, you can click annotations to highlight the point cluster each annotation corresponds to.

Select ELAN tier

Export CSV

In the "Plot" view you can inspect telemetry as a plot over time or - for geo-data - distance. Select a value for each axis and export the full-resolution plot as a CSV-file.

Plot view

Command line (CLI) version

Install

See releases to the right for pre-compiled binaries for Windows (x86), macOS (Apple Silicon, x86). Linux is also supported but currently lacks a pre-compiled version due to path issues for the documentation when using cargo cross.

Note that some operating systems (most notably macOS) will not run unsigned binaries without user intervention, see https://support.apple.com/guide/mac-help/mh40616/mac for more information.

Compile and install from source

You can also compile GeoELAN yourself. The full build requires the Typst command line tool to be present in path to compile the GeoELAN documentation. Remove build.rs or change its name to skip this step.

The basic steps are:

  1. Install the Rust programming langugage toolchain
  2. Get the source: git clone https://github.com/jenslar/geoelan
  3. cd geoelan/cli (you should be in the folder containing Cargo.toml)
  4. cargo build --release
  5. cargo install --path . (optional, makes geoelan a global command)

Examples

Locate all low-resolution GoPro clips (.LRV) in ~/Desktop/ for session the containing the high-resolution clip GX020006.MP4, join them and generate an ELAN-file with a tier containing coordinates, and altitude as time series:

geoelan cam2eaf --source ~/Desktop/gopro/GX010006.MP4 --indir ~/Desktop/ --geo --outdir ~/Desktop/

(if --indir is not specified, GeoELAN will search the parent folder for the specified clip)

Prompts the user to select a tier to geo-reference, then generates a KML and GeoJSON files with a continuous poly-line, alternating between annotated and un-annotated sections. Relevant GoPro files are automatically located.

geoelan eaf2geo --eaf ~/Desktop/gopro/MYELANFILE.eaf --gpmf ~/Desktop/gopro/GX010006.MP4 --indir ~/Desktop/ --geoshape line-all

Specified --source file must be an original MP4-file. Files can be renamed, but not converted in any way. Joined recording sessions (done via geoelan cam2eaf ... or using FFmpeg directly) will not contain any telemetry, such as the GPS log.

Locate all GoPro clips and group them according to recording session:

geoelan locate --indir ~/Desktop/ --device gopro

Locate remaining clips in session containing GX020006.MP4 (does not have to be the first clip in the session):

geoelan locate --indir ~/Desktop/ --source ~/Desktop/gopro/GX020006.MP4

Generate a KML-file from the merged GPS-log for session containing GX020006.MP4:

geoelan cam2geo --source ~/Desktop/gopro/GX010006.MP4 --outdir ~/Desktop/ --export-gps kml

Print MP4 atom layout (similar to AtomicParsely):

geoelan inspect --source ~/Desktop/gopro/GX010006.MP4 --tree

Print MP4 user data (udta atom), including GPMF data if encountered (this is different to the timed GPMF telemetry and contains device specific information):

geoelan inspect --source ~/Desktop/gopro/GX010006.MP4 --metadata

--video VIDEOFILE tells GeoELAN to inspect the file as an MP4 video, ignoring e.g. timed GPMF telemetry.

Plot the accelerometer data in a GoPro MP4 file (opens in default browser):

geoelan plot --source ~/Desktop/gopro/GX010006.MP4 --y-axis accelerometer

Annotating placename utterances in ELAN, to be geo-referenced by GeoELAN Annotating placename utterances in ELAN

Using GeoELAN to geo-reference ELAN annotations Using GeoELAN to geo-reference ELAN annotations

Example walkthrough

Please note that this section only concerns the command line version. The may be errors below since several flags and options changed in version 3.0. All documentation is being updated but this may take a while.

This section describes how GeoELAN can be used to geo-reference ELAN-annotations. Please refer to the detailed sections if you get stuck. Remember that all input video clips must be the unprocessed, original MP4 (GoPro + VIRB) and FIT-files (VIRB). The so-called FIT-files mentioned throughout this manual are where the VIRB logs GPS-data and other kinds of telemetry during a recording session. These need to be matched to the corresponding video recording. GeoELAN will help with all of this, with the exception of annotating your data.

Note that some commands differ slightly between GoPro and VIRB.

The basic steps are:

  1. Record video with a recent GoPro or VIRB.
  2. Use GeoELAN to concatenate the video clips and generate an ELAN-file.
  3. Annotate spatially interesting sections in ELAN.
  4. Use GeoELAN to geo-reference the annotations, resulting in annotated KML and GeoJSON files.

Input files:

  • GoPro:
    • GH010026.MP4, any clip in a recording session (remaining clips located automatically)
  • VIRB:
    • VIRB0001-1.MP4, any clip in a recording session (remaining clips located automatically)
    • FIT-file with corresponding GPS-data (located automatically)

Output files:

  • GoPro + VIRB:
    • KML and GeoJSON files with ELAN annotation content synchronised and mapped to the corresponding points as descriptions.

Step 1/3: Generate an ELAN-file with linked media files

In step 1 we will locate all video clips (GoPro + VIRB) and FIT-files (VIRB) that belong to a specific recording session, process these, join clips, and generate an ELAN-file with linked media files.

Command

geoelan cam2eaf --source INDIR/VIRB_OR_GOPRO_CLIP_.MP4 --indir INDIR/ --outdir OUTDIR/

Output files GoPro

OUTDIR/GH010026/
├── GH010026.mp4             High-resolution video (concatenated)
├── GH010026_LO.mp4          Low-resolution video for ELAN (concatenated)
├── GH010026.wav             Extracted audio for ELAN (concatenated)
├── GH010026.eaf             ELAN-file with pre-linked media files
├── GH010026.kml             Overview KML-file with all points logged during the recording session
└── GH010026.txt             FFmpeg concatenation file, paths to input clips

Output files VIRB

OUTDIR/VIRB0001-1/
├── 2017-05-29-13-05-42.fit  FIT-file with corresponding telemetry
├── VIRB0001-1.mp4           High-resolution video (concatenated)
├── VIRB0001-1_LO.mp4        Low-resolution video for ELAN (concatenated)
├── VIRB0001-1.wav           Extracted audio for ELAN (concatenated)
├── VIRB0001-1.eaf           ELAN-file with pre-linked media files
├── VIRB0001-1.kml           Overview KML-file with all points logged during the recording session
└── VIRB0001-1.txt           FFmpeg concatenation file, paths to input clips

By specifying any clip in the recording session via --video, remaining files will be automatically located, if they exist in the input directory INDIR/. The result, including an ELAN-file with linked media files, will be saved to the output directory OUTDIR/. The default behaviour is to link low-resolution clips (.GLV/.LRV) in the ELAN-file.

Step 2/3: Annotate events in ELAN

Next, use ELAN with the ELAN-file from step 1 to annotate events that should be geo-referenced in step 3. Feel free to create any tier structure you may need. Tokenized tiers can not be geo-referenced, but otherwise any tier is fine, including deeply nested, referred tiers.

GeoELAN will geo-reference annotations from a single tier (selectable in step 3). Thus, if you want to generate a KML-file with e.g. indigenous place names mentioned on-site during the recording, those place names must be limited to a single tier. If there are other spatial categories or groupings you wish to explore, simply create a new tier for each. In step 3 you can then re-run GeoELAN as many times as required, then select a different tier and/or options on each run.

When the annotations are geo-referenced in step 3, the annotation values in the selected tier will be used as descriptions for the synchronized, corresponding points in the KML and GeoJSON-files. Points corresponding to unannotated sections of the ELAN-file will either be discarded or have no description, depending on which options you use in step 3.

An annotated event can relate to anything observed in the recording and can be represented as either points or polylines in the output KML-file. If you are unsure which best applies to what you have in mind for your data, or how this may affect how you annotate, here are a few ideas for each kind.

Points could concern documenting:

  • the location of a plant or a geographical feature, e.g. annotate the timespan either is visible in the video.
  • an uttered place name or an animal cry, e.g. annotate the timespan of the on-site utterance or cry.

Lines could concern documenting:

  • various types of movement through the landscape. To annotate the movement of "walking up-hill" as it is observed visually in the recording, set the annotation's start time at the bottom of the hill and its end at the top, or for as long as the motion can be observed.
  • a narrative reflecting on the immediate surroundings as they change over time. E.g. comments on visible landscape features, or perhaps the re-construction of an historical event as it unfolded over space and time.

Step 3/3: Generate a KML-file from geo-referenced ELAN annotations

Now that we have a few annotations, GeoELAN will geo-referenence these by determining which points were logged within each annotation's timespan. Note the different commands between GoPro and VIRB.

This is where you choose the approriate geographical representations for your annotated phenomena. Here are suggestions for the examples in step 2.

Points:

  • the location of a plant or a geographical feature
  • an uttered place name or an animal cry

To get a single, average coordinate for each annotation, use the --geoshape point-single option.

Lines:

  • types of movement through the landscape
  • narrative reflecting on the immediate surroundings

There are other options, such as circle output. It is the same as point output with the difference that radius and height can be specified (all circles will have the same size). For a more detailed overview of the possibilities, see the --geoshape option for the command eaf2geo. Experiment! If you realise one representation is not appropriate after all, re-run GeoELAN with a different option.

GoPro

Command

geoelan eaf2geo --eaf GH010026.eaf --source INDIR/GH010026.MP4  --geoshape point-single

Important: GH010026.MP4 must be an unedited GoPro clip from the recording session, as it was generated by the camera, not the video linked in your ELAN file. E.g. the same one specified in step 1.

Output files

OUTDIR/GH010026/
├── ...                            Existing files
├── GH010026_point-single.kml      New KML-file, one point per annotation in the selected tier
└── GH010026_point-single.json  New GeoJSON-file, one point per annotation in the selected tier

Explanation of the command

GeoELAN geo-references all annotations in a single ELAN-tier (you will be prompted to select from a list) for the specified ELAN-file, then generates annotated KML and GeoJSON files where each point represents a single annotation.

By specifying an ELAN-file (--eaf) and an original, unedited GoPro MP4-clip (--gpmf) or VIRB FIT-file (--fit), GeoELAN will synchronise the annotations with the coordinates contained within the MP4/FIT-file. Similar to step 1, all files will be automatically located.

--geoshape point-single lets GeoELAN know that each, respective annotation should be distilled into a single point, meaning that the generated KML-file will contain as many points as there are annotations in the selected tier. Each point inherits the corresponding annotation value as its description. The KML-file is named according to the selected --geoshape option, in this case GH010026_point-single.kml/VIRB0001-1_point-single.kml.

For the example command for VIRB, the user will be presented with a list of recording sessions present in the FIT-file (see The FIT-format and the Garmin VIRB). For GoPro, specifying an original clip, e.g. the same one specified in step 1, is enough.

References

Larsson, Jens, Niclas Burenhult, Nicole Kruspe, Ross. S Purves, Mikael Rothstein and Peter Sercombe. 2020. Integrating behavioral and geospatial data on the timeline: towards new dimensions of analysis. International Journal of Social Research Methodology. doi: 10.1080/13645579.2020.1763705

ELAN (Version 7.1) [Computer software]. 2026. Nijmegen: Max Planck Institute for Psycholinguistics. Retrieved from https://archive.mpi.nl/tla/elan

Acknowledgements

GeoELAN was developed with support from the European Research Council, 2024 Starting Grant project no. 101162052, and Bank of Sweden Tercentenary Foundation (Grant nos NHS14-1665:1 and IN17-0183:1).

We would also like to acknowledge the The Language Archive, Max Planck Institute for Psycholinguistics in Nijmegen, the Netherlands for their tireless efforts in developing ELAN, and making it available for free.