VAME Desktop

A desktop application for the Variational Animal Motion Encoding (VAME) project.

Overview

VAME Desktop has been designed to run each step of a VAME project only once. This is to ensure that the project is reproducible and that the data is not accidentally overwritten.

Installation

Requirement:

For some images functions (as UMAP images) ffmpeg is needed.

Download page: https://www.ffmpeg.org/download.html

Download Desktop versions:

You can find installers for VAME Desktop on the release page.

MacOS

For M-series Macs, download the -arm64.dmg. For Intel Macs, download the -x64.dmg.

Open the vame-desktop-<VERSION>-macos-arm64.dmg or vame-desktop-<VERSION>-macos-x64.dmg, and drag and drop the VAME Desktop into the Applications folder.

Then go to Applications in Finder.

Hold Control ^ on the keyboard, then click open. In the following window, click on open again. This process needs to be done once. After that, the app can be opened from Launchpad as usual.

Windows

Double-click on vame-desktop-<VERSION>-win-setup.exe. The app will be installed and a shortcut named VAME Desktop will be added to your Desktop. Double-click on it to launch the app.

Linux Debian

Double-click on vame-desktop-<VERSION>-linux.deb or

sudo dpkg -i vame-desktop-<VERSION>-linux.deb

The executable will be added to the main applications folder on your Linux distribution.

Example data

The app can be tested on the sample input data found here.

Development mode

Python

You will need to have miniconda installed on your machine OR pyenv.

with pyenv:

pyenv local

python -m venv venv

Unix system (linux or macos):

source ./venv/bin/activate

Windows:

.\venv\Scripts\activate.bat

This will install all the necessary Python dependencies for the project.

python -m pip install -r requirements.txt

with conda:

Create the Conda environment for the project by running the following command:

conda env create -f environment.yml

This will install all the necessary Python dependencies for the project.

Once complete, activate the environment by running the following command:

conda activate vame-desktop

Node.js

You will need to have Node.js 20 installed on your machine. You also can use nvm or n to select versions.

Install Node modules by running the following command:

npm install

This only needs to be run once at project initialization and when the package.json dependencies are updated.

Running the App

To run the app, you will need to run the following command:

npm run dev

This will start the Electron app on developer mode.

Build:

The build process will create a .exe, .dmg or .deb depend on OS. Run differents command on incompatible OS will result on error.

MacOS

npm run build:mac

Windows

npm run build:win

Linux Debian

npm run build:linux

Publish

Publishing will happen every time a new push is maded to the main branch with a tag associated, creating a release at release page.

To avoid unecessary releases, follow these steps:

• Create a branch git checkout -b <branch_name>, work on it, and create a pull request to main.
• Update the package.json with the new version number.
• Create a new tag with git tag v<tag_number>, push it to the repo with git push orgin --tags. IMPORTANT: the tag must be in the format vX.Y.Z where X.Y.Z is the package version number in package.json.
• Create a draft release on github using the tag created.
• Merge the PR from <branch_name> into main. The github action will publiss the executable assets to the draft release.
• Manually edit the draft release, add information about the new features, bug fixes, and breaking changes.
• Finaly approve and publish the new release.