Getting Started

Installation and Setup

Note

The instructions on this page only need to be carried out once. If you have already installed the required dependencies, skip ahead to Configurations or Using the Utility.

There are multiple ways to set up this utility depending on one’s familiarity with Git, R, Python, and/or command line. In order of increasing technical complexity, the options are:

No command line

1. Clone the repository (preferred) using GitHub Desktop OR download the repository by clicking the green “Code” button and selecting “Download ZIP.” Extract the contents of the ZIP file to a local directory.

Warning

Downloading the repository does not support version control, so you will not be able to easily update the utility as improvements are made. Cloning the repo is recommended instead.

Branching best practice

It is recommended to create a new branch for any changes or experiments. This allows you to work without affecting the main branch and minimize version conflicts in the future.

2. Set up the environment and install dependencies: Open File Explorer (Windows) and navigate to the newly extracted project directory. Run (double-click) the setup.bat file. This will do three things behind the scenes:

Create a Python virtual environment in the project directory (called .venv) for package management.
Install the required Python dependencies (from requirements.txt) into the virtual environment.
Download and extract ffmpeg into the project directory. This contains two utilities, ffmpeg and ffprobe, which are used for video processing and metadata extraction, respectively.

3. Use the utility as described in Using the Utility.

RStudio and R

For users comfortable using R, RStudio, and Git version control, but unfamiliar with Python or command line:

Clone the repository directly into RStudio: Create a new project, select “Version Control”, then “Git.” Paste the URL of this repository (https://github.com/SEFSC/PEM-ACRF-SEFIS-VideoPreProcessing) into the “Repository URL” field, enter a name for the local project directory, and select a local directory to clone the repository into. This will create a new RStudio project with all of the files in this repository.
Setup the environment and install dependencies: Open File Explorer (Windows) and navigate to the newly created project directory. Run (double-click) the setup.bat file, as above.
Use the utility as described in Using the Utility.

Python and command line

In the instructions below, “command line terminal” or “terminal” refer to any command line application for the given operating system. For Windows, this is commonly Command Prompt or Windows Powershell, both of which use DOS commands. For UNIX users, Git Bash is a good alternative; it is included in Git for Windows and allows UNIX commands to be used instead of DOS.

Install Git, if needed: If the Git CLI is already installed, there should be a Git Bash program in your Applications. If so, open this program and verify everything is working by typing
```
git --version
```
This should display the version of git installed on the system.

If needed, download and install the Git CLI before continuing. This does not need administrative privileges to install at the user level. Confirm that it has been installed by opening a command line terminal and entering git --version.
Clone the repository: Open a command line terminal and navigate to the directory where you want to clone the repository. To clone all of the repo contents into the current directory, use:
```
git clone https://github.com/SEFSC/PEM-ACRF-SEFIS-VideoPreProcessing .
```
or, if you want the repo contents to be downloaded into a new subdirectory called PEM-ACRF-SEFIS-VideoPreProcessing, use:
```
git clone https://github.com/SEFSC/PEM-ACRF-SEFIS-VideoPreProcessing
```
(This is just personal preference. Note the difference between the two commands is the dot . at the end.)
Set up the environment and install dependencies: Run the setup.bat file, as above, or manually create your own virtual environment. In a command line terminal, navigate to the repository directory. For example,
```
cd "c:/Users/user.name/Documents/PEM-ACRF-SEFIS-VideoPreProcessing"
```
Create and activate a Python virtual environment and install the package dependencies. The setup.bat file creates an environment named .venv, but you can call it whatever you want. For example,
```
Windows Command Prompt
```
```
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```
```
Git Bash
```
```
python -m venv .venv
source .venv/Scripts/activate
pip install -r requirements.txt
```
```
Linux or Mac Terminal
```
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
or, if using Anaconda:
```
conda environment
```
```
conda create --name video-processing-venv python=3.14 --file requirements.txt
```
Important

If you plan to use the process_videos.bat or process_videos.R provided in the repo, you must use a pip environment named .venv and place it in the project directory, as these scripts are configured to look for the virtual environment in that location. If you create a virtual environment with a different name or in a different location, you will need to modify those scripts to point to the correct environment.
Use the utility as described in Using the Utility.

Deactivate the virtual environment when finished:

pip environment

deactivate

conda environment

conda deactivate