diff --git a/.gitignore b/.gitignore index b2d6de3..33a2d6c 100644 --- a/.gitignore +++ b/.gitignore @@ -14,7 +14,8 @@ .env.development.local .env.test.local .env.production.local - npm-debug.log* yarn-debug.log* yarn-error.log* +.Rproj.user +gc-docs.Rproj diff --git a/docs/guides/guide-timelapse-project/index.md b/docs/guides/guide-timelapse-project/index.md index 2ac2a14..2f6c837 100644 --- a/docs/guides/guide-timelapse-project/index.md +++ b/docs/guides/guide-timelapse-project/index.md @@ -6,7 +6,7 @@ sidebar_position: 2 ## Introduction -[Timelapse](https://timelapse.ucalgary.ca/) is a **Windows OS software for reviewing camera trap data and transforming raw image and video files into structured data** that can provide insights into species presence and population trends. This is a quick introduction to using the software. +[Timelapse](https://timelapse.ucalgary.ca/) is a **Windows OS software for reviewing camera trap data and transforming raw image and video files into structured data** that can provide insights into species presence, diversity, and population trends. This is a quick introduction to using the software. ![Timelapse Software screenshot](images/timelapse.jpg) @@ -16,7 +16,11 @@ Timelapse is actively developed, open source ([GitHub repo](https://github.com/s ::: -## Key Resources +## Installing Timelapse + +Timelapse can be downloaded [here](https://timelapse.ucalgary.ca/download/). There are three different install methods. We recommend using the "1 MSI Per-User Installer (recommended for most)" unless there is some reason you need to use one of the other install methods. + +## Key Resources from the Timelapse Developers - :house: [Timelapse Home Page](https://timelapse.ucalgary.ca/) - :arrow_down: [Download and Installation](https://timelapse.ucalgary.ca/download/) diff --git a/docs/guides/guide-timelapse-project/step-2-creating-a-timelapse-template.md b/docs/guides/guide-timelapse-project/step-2-creating-a-timelapse-template.md index 569bc9b..7d6587d 100644 --- a/docs/guides/guide-timelapse-project/step-2-creating-a-timelapse-template.md +++ b/docs/guides/guide-timelapse-project/step-2-creating-a-timelapse-template.md @@ -33,20 +33,21 @@ _Example of a Timelapse template, using the practice image set._ **Suggested fields:** -- `Species` (**Choices**) — count the species found in the image +- `Indigenous Name` (**Choices** or **text**) — Indigenous Name for the species found in the image +- `English Name` (**Choices**) — English name for the species found in the image (optional) +- `Scientific Name` (**Choices**) — Scientific name for the species found in the image (optional) - `Count` (**Counts**) — count the number of species - `Notes` (**Notes**) — for reviewer comments -- `Highlight` (**Flag**) — to mark notable images -- Additional `Notes` field — for general observations +- `Favorite` (**Flag**) — to mark notable images :::tip -You don't have to use scientific names for your species dropdown if you don't want to. You can use Indigenous names instead, and later join those with scientific names (if so desired.) +You don't have to use scientific names for your species dropdown if you don't want to. You can use Indigenous names instead, and later join those with scientific names (if so desired). ::: :::info -Your project template data is stored in a file called `TimelapseTemplate.tdb`. Please make sure this file is always at the root level of your imagery set. (Timelapse will create it there when you start a new project.) +Your project template data is stored in a file called `TimelapseTemplate.tdb`. You may rename this file as long as you do not have special characters or spaces in the filename. Please make sure this file is always at the root level of your imagery set. (Timelapse will create it there when you start a new project.) -::: \ No newline at end of file +::: diff --git a/docs/guides/guide-timelapse-project/step-3-setting-up-folder-metadata.md b/docs/guides/guide-timelapse-project/step-3-setting-up-folder-metadata.md index 6db5928..841d4dc 100644 --- a/docs/guides/guide-timelapse-project/step-3-setting-up-folder-metadata.md +++ b/docs/guides/guide-timelapse-project/step-3-setting-up-folder-metadata.md @@ -12,7 +12,15 @@ Timelapse supports folder-level metadata, which allows you to associate project, _Example of Timelapse project folder-level metadata, using the practice image set._ :::tip -Before enabling folder-level metadata, think through your folder hierarchy and naming conventions. Changes later can break links between data and folders, so it’s best to finalize your structure first. + +Before enabling folder-level metadata, think through your folder hierarchy and naming conventions. Changes later can break links between data and folders, so it’s *important* to finalize your structure first. + +::: + +:::important + +Adding folder-level metadata into Timelapse is completely optional. If you already have a more sophisticated method for collecting station and deployment metadata and that information is already digitized, there is no need to add these types of metadata to the Timelapse itself. + ::: ## How to set up Folder metadata @@ -39,7 +47,7 @@ Timelapse does not have the ability to set custom field validations beyond what For example, for Latitude and Longitude fields, these can be set up as Number fields of Decimal type to allow for positive and negative decimal coordinates. But it is **not** possible to set limits of 180 to -180 or 90 to -90; so basically _any_ decimal number can be entered. -Hence, it is important to be very careful when doing data entry into the Timelapse Template Editor for these kinds of fields. +Hence, it is important to be very careful when doing data entry into Timelapse for these kinds of fields. ::: @@ -60,7 +68,10 @@ Examples of useful metadata fields might include (but you may want to refer to t * Camera Trap ID * Site or Station Name * Latitude and Longitude -* Deployment Start and End Dates +* Camera Height +* Camera Field of View +* Deployment Start and End Dates/Times +* SD Card number * SD Card Retrieval Notes * Observer or Team Member Name diff --git a/docs/guides/guide-timelapse-project/step-4-reviewing-and-tagging-images.md b/docs/guides/guide-timelapse-project/step-4-reviewing-and-tagging-images.md index 834cbc9..ddb4ded 100644 --- a/docs/guides/guide-timelapse-project/step-4-reviewing-and-tagging-images.md +++ b/docs/guides/guide-timelapse-project/step-4-reviewing-and-tagging-images.md @@ -10,9 +10,14 @@ The process of reviewing and tagging photos will vary depending on your image da - This will load your images into Timelapse. 3. **Review and tag images:** - - Move through each image, identifying all animals present. + - Move through each image (using the arrow keys **← →**), identifying all animals present. + - If your camera traps were set up to shoot multiple images each time it was triggered, you can move forward or back an "episode" (all images in a sequence) using **ctrl+→** or **ctrl+←** + - the **c** key will copy the the values from the previous image and fill them in on the current image. This only applies to "copyable" fields in the Timelapse template for your project. + - the **↑** and **↓** keys will show the difference between the current image and the next / previous image highlighting pixels that changed. This is helpful for spotting where an animal is in the image. - If more than one species appears in an image or video, use **Edit → Duplicate this record** (`Ctrl+D`). - - This will create an additional entry in the database, allowing you to annotate each species separately. + - This will create an additional entry in the database, allowing you to annotate each species separately. + - You can use **Select → Custom selection...** to filter what images are viewed to focus on specific metadata fields (folders, Favorited images, date/time range, etc) + - Timelapse has a built-in image adjuster that can be used to change the contrast, brightness, and apply temporary transformations to the current image. This option can be accessed **Options → Temporarily adjust image appearance**. ![Review and tag images](images/tagging-animals.jpg) _Example of tagging images in Timelapse using the practice image set._ diff --git a/docs/guides/guide-timelapse-project/step-5-using-image-recognition.md b/docs/guides/guide-timelapse-project/step-5-using-image-recognition.md index dd1fa40..93ee237 100644 --- a/docs/guides/guide-timelapse-project/step-5-using-image-recognition.md +++ b/docs/guides/guide-timelapse-project/step-5-using-image-recognition.md @@ -30,6 +30,8 @@ The process works on videos too - frames are extracted and analyzed as images, w Timelapse integrates with **AddaxAI** (formerly called EcoAssist), which provides an easy interface to Microsoft's widely-used [MegaDetector](https://github.com/agentmorris/MegaDetector) AI recognition system. MegaDetector is specifically designed for wildlife camera trap images and is one of the most reliable detection systems available for ecological research. +AddaxAI also allows running of **SpeciesNet**, a global species recognition model, as well as several region- or habitat-specific models. + ### Installation 1. **In Timelapse, select** `Recognizer → AddaxAI Image Recognizer → Install AddaxAI image recognizer` diff --git a/docs/guides/guide-timelapse-project/step-7-multiple-annotation-computers.md b/docs/guides/guide-timelapse-project/step-7-multiple-annotation-computers.md new file mode 100644 index 0000000..9c27773 --- /dev/null +++ b/docs/guides/guide-timelapse-project/step-7-multiple-annotation-computers.md @@ -0,0 +1,136 @@ +# Appendix 1: Enabling >1 computer for Labeling + +Large Timelapse projects often involve multiple site folders, each containing its own copy (“child set”) of the project database (`.ddb`). Timelapse allows you to check out subsets of a project, annotate them independently (on a different computer or user), and then merge the changes back into the primary database. This workflow helps teams scale up annotation across many sites or observers. + +This section describes how to work with an **existing master `.ddb` file**, how to create and manage child sets, and how to merge them safely back into the main project. + +--- + +# Quick Start: Merging Timelapse Databases + +If you are working on a large Timelapse project with multiple site folders, use the check-out / check-in workflow to keep all annotations synchronized with a single master `.ddb` file. + +### Quick Workflow + +1. **Open the master `.ddb`** in the project root. +2. **Check out** a child set: + - Go to *File → Merge Datasets → Check out (copy) a sub-folder database from the master database...*. + - Select a site or subfolder to create a child `.ddb`. +3. **Annotators work only in the child `.ddb`** inside that subfolder. +4. When annotation is complete, the child `.ddb` is returned to the project manager. +5. **Check in the child `.ddb`**: + - Open the master `.ddb`. + - Go to *File → Merge Datasets → Check in (merge) a sub-folder’s database into the master database...*. + - Select the child `.ddb` to merge changes back into the master. + +### Key Rules + +- **Do not annotate in the master `.ddb`** once child sets have been created. +- **Do not change field definitions** in child sets. +- Always **check out from the master** and **check in to the master**. +- Use **consistent folder naming** for sites/stations to keep merges clean. + +This workflow scales cleanly across many annotators and ensures the master database remains the authoritative source for all project metadata. + + +--- + +## Overview + +Timelapse supports a *check-out / check-in* system designed for large datasets spread across multiple subfolders. The general workflow is: + +1. **Start from the master `.ddb`** located in the root of the project. +2. **Check out** child sets into site-level folders (or any subfolder structure you use). +3. Annotators open and work only within the checked-out child `.ddb` files. +4. After annotation is complete, the child `.ddb` files are **checked back in**, merging changes into the master. + +This ensures that all metadata, annotations, and derived fields are consolidated into a single authoritative database. + +--- + +## Preparing the Master Database + +Before creating child sets: + +1. Open the **master** project `.ddb` in Timelapse. +2. Confirm that: + - The image root folder is correct. + - Templates and field definitions are up-to-date. + - The master `.ddb` opens without errors and displays all images as expected. + +If needed, run **File → Expose Missing Images** or **Reindex Folders** to confirm the project structure is healthy. + +--- + +## Checking Out Child Sets + +### When to Create Child Sets + +You should create child sets when: + +- Annotators will work on different deployment or site folders independently. +- You want to avoid multiple users modifying the master `.ddb` simultaneously. +- The project contains thousands of images and needs to be split for performance. + +### How to Check Out a Child Set + +1. Open the **master `.ddb`**. +2. Go to **File → Merge Datasets → Check out (copy) a sub-folder database from the master database...**. +3. In the folder tree, select the **subfolder** you want to create a child set for +(e.g., individual camera stations or Deployments). +4. Timelapse creates: + - A **child `.ddb` file** inside the selected folder. + - A copy of the field definitions and metadata for only the images in that subfolder. + +Each child set contains everything needed for annotators to work independently in Timelapse. + +### What Annotators Do + +Annotators should: + +- Open the **child `.ddb`** directly from the subfolder. +- Annotate normally. +- Avoid moving or renaming image files during annotation. +- Avoid changing field definitions (these should be controlled from the master). + +When finished, annotators return the `.ddb` to the project manager for check-in. + +--- + +## Checking In Child Sets (Merging Back to Master) + +When all annotations for a child set are complete: + +1. Move or copy the **child `.ddb`** back to its original subfolder on the computer that manages the master `.ddb` (if it isn’t already there). +2. Open the **master `.ddb`**. +3. Go to **File → Merge Datasets → Check in (merge) a sub-folder’s database into the master database...**. +4. Select the child `.ddb` to merge. + +Timelapse will: + +- Compare the child set’s annotations with the master. +- Merge new or updated metadata and annotations. +- Preserve existing data in the master where necessary. +- Flag conflicts if a record was edited in both the master and the child set. + +### Typical Conflict Handling + +Conflicts are rare if only annotators modify the child sets. When conflicts occur, Timelapse presents a dialog allowing you to choose which version to keep. + +After check-in finishes, the master `.ddb` contains all updated annotations for that subfolder. + +--- + +## Best Practices for Large Projects + +- **Never annotate directly in the master database** once *child sets have been created*. +- **Use consistent folder names** that already exist in the project folder structure for site or station-level child sets. +- Always **check out** using the master and **check in** to the same master. +- Do not alter field definitions inside child databases; manage fields only from the master. +- After all child sets are checked in, **back up the master `.ddb`** and consider exporting CSVs for downstream processing. + +--- + +## Summary + +Timelapse’s check-out / check-in system provides a robust workflow for large camera-trap projects. By starting with a single master `.ddb`, distributing child sets across subfolders, and merging annotations back in, teams can annotate large datasets efficiently while maintaining a single unified project database. diff --git a/docs/guides/guide-timelapse-project/step-8-how-delete-files-and-data.md b/docs/guides/guide-timelapse-project/step-8-how-delete-files-and-data.md new file mode 100644 index 0000000..01b64e0 --- /dev/null +++ b/docs/guides/guide-timelapse-project/step-8-how-delete-files-and-data.md @@ -0,0 +1,128 @@ +# Appendix 2: Deleting Files and Data + +Timelapse provides several tools for removing images, records, and associated metadata from a project. Deletions are permanent, so these tools should be used with care—especially when working in a shared or multi-annotator project. + +This section summarizes the recommended workflow for safely deleting files and data within an existing Timelapse project. + +--- + +# Quick Start: Deleting Files and Data + +Use Timelapse’s deletion tools to remove images, records, or empty folders while keeping the project database synchronized. Deletions are permanent, so always confirm before proceeding. + +### Quick Workflow + +1. **Delete files + records** + - Select images → *Edit → Delete → All selected image or video files marked for deletion and their data* + - Removes the image files from disk and deletes their metadata. + +1. **Delete files** + - Select images → *Edit → Delete → All selected image or video files marked for deletion* + - Removes the image files from disk (or sends them to the "DeletedFiles" folder depending on your Preferences). + +2. **Delete records only (keep files)** + - Select records → *Edit → Delete → Only the data associated with all selected image or video files marked for deletion…* + - Removes metadata from the `.ddb` but leaves image files untouched. + +3. **Check for missing files first** + - Run *Edit → Try to find this (and anyother) missing files...* to ensure deletions are intentional. + +### Key Rules + +- Always **back up the master `.ddb`** before bulk deletions. +- Perform deletions only in the **master database** (not child sets). +- Use “Delete Records Only” if you are uncertain—files can be re-imported later. +- Avoid deleting files that may be needed for QC, machine-learning workflows, or future annotation. + +This workflow helps maintain a clean, synchronized project while minimizing accidental data loss. + +--- + +## Overview + +There are many reasons that files may need to be deleted from a project: + +- Duplicates Images are discovered in the data set. +- Images from before or after a deployment are made due to a camera recording after it is removed from a site. +- Pictures are of a sensitive nature: explicit, record illegal activity, show people without their consent. +- Images are empty and your organization/collaborators have no plans to train detection models in the future. + +We generally recommend to save all images collected by the cameras, however, each project will need to decide on their own policy and workflow. + +--- + +Timelapse allows you to delete: + +- Image files +- Associated database records +- Empty folders that contain no remaining images +- Records only (while leaving image files untouched) + +In all cases, Timelapse ensures that the project database stays synchronized with the underlying image folder structure. + +To delete files, you must first mark the files you wish to delete with the "Delete?" flag. Only images that have been marked with this flag AND are in your current selection will be deleted. + +The behavior of Timelapse delete functionality can be configured in the **Options → Preferences → How to deleted files are managed**. By default, image files that are "deleted" and not actually removed from disk, but instead they are moved into a the root folder into a new subfolder called "DeletedFiles". This way they are removed from the project but recoverable. + +:::tip +To be able to use the delete functionality in Timelapse for >1 file at a time, you must have the "Delete?" flag field marked "Visible" in your Template. +::: +--- + +## Deleting Image Files and Records + +Use this option when you want to remove **both the files and the database entries**. + +1. Select the image(s) you want to delete in the Filmstrip or Grid View. +2. Go to **Edit → Delete → All selected image or video files marked for deletion and their data**. +3. Review the confirmation dialog. Timelapse will list: + - The number of files to be deleted + - The number of database records that will be removed +4. Confirm to permanently delete the selected files from disk (or put them in the DeletedFiles folder depending on your settings) and remove their metadata from the `.ddb`. + +This action cannot be undone. Only use it when you are certain the images should no longer be part of the project. + +--- + +## Deleting Records Only (Keeping Files) + +Use this option when the **image files should remain**, but their Timelapse metadata needs to be removed (e.g., when re-importing or reprocessing folders). + +1. Select the records to remove. +2. Go to **Edit → Delete → Only the data associated with all selected image or video files marked for deletion…**. +3. Confirm the action in the dialog. + +Timelapse will remove the metadata rows from the `.ddb`, but the image files remain in the folder. + +This is useful when: +- A folder was annotated incorrectly and you want to start over. +- You are re-running import or template steps. +- You are cleaning up duplicate database entries. + +--- + +## Handling Missing Files Before Deletion + +Before deleting any records, validate that missing or moved files are intentional. + +Use: + +- **File → Expose Missing Files** + to highlight database entries that no longer match files on disk. + +This helps ensure you are not deleting records accidentally created by path mismatches or folder restructuring. + +--- + +## Best Practices + +- **Back up the `.ddb` file** before doing large deletions. +- For multi-user workflows, perform deletions only in the **master `.ddb`**, not in child sets. +- Avoid deleting files if they may be needed for re-annotation, machine-learning extraction, or downstream QC. +- Use “Delete Records Only” when you are unsure—files can be re-imported but deleted images cannot be restored. + +--- + +## Summary + +Timelapse provides flexible tools for permanently deleting files and records or cleaning up only the database entries. Use file deletion when the images truly do not belong in the project, and use record-only deletion when you need to reset or reorganize database entries while preserving the underlying files.