Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates README and USAGE for improved readability #101

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+68 −66
Open

Updates README and USAGE for improved readability #101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 66 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,83 @@
# AVAT
# Animal Video Annotation Tool (AVAT)

The front-end dashboard that provides the ability to annotate videos of livestock for the use in research.
AVAT is a front-end dashboard that can annotate videos of livestock, utilized for various academic disciplines and providing a robust interface for efficient video annotation. This document outlines the key features of the platform, including user interface details, key bindings, and the process for uploading media and annotating videos.

## Goals
The goal of this project is to create a tool that is easy to use, has a small learning curve and can scale easily to provide the ability to annotate videos efficiently and at scale. The intuition of this project is gained from analyzing similar projects and analyzing the weaknesses and points of frustration and improving them. Another goal is to have an annotation workflow that is extremely fast and efficient, as there are terabytes of video that needs to be processed at large.
For a system that spans multiple academic disciplines, ensuring a robust interface allows a person of any experience to efficiently annotate videos. A potential user should be able to identify animals of interest easily and have a method to track them across frames in an easy and efficient manner. For a more efficient workflow, a series of key bindings was implemented to expedite each operation within the platform, therefore allowing unexperienced users to familiarize themselves with a predetermined workflow efficiently.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: this info was in the Usage but sounds awkward when placed here. Might need to be split up and parts merged into the intro and goals


## USAGE
Please refer to [USAGE.md](https://github.com/AIFARMS/AVAT/blob/master/USAGE.md) for a detailed guide on how to use the tool.
### Goals

## Local Deployment (Frontend)
AVAT aims to simplify the video annotation process, allowing users to easily identify and track animals of interest across frames. A significant challenge addressed was conditioning users to adopt a predetermined workflow for increased efficiency, even without prior intensive training on our system.

These instructions will get you a copy of the project up and running on your local machine for viewing.
AVAT was designed for ease of use, and to scale easily in order to annotate videos efficiently. The intuition of this project is gained from analyzing similar projects and analyzing the weaknesses and points of frustration and improving them.

### Prerequisites:
Another goal is to have an annotation workflow that is extremely fast and efficient, as there are terabytes of video that need to be processed at large.

You will need to have npm, firefox/chrome and git installed on your system for this to work.
## Deploying AVAT

### Installing and Building:
The AVAT platform offers multiple methods of deployyment covered in this README. Currently supported:

First, you will need to clone the repository to your desired location
* [Direct browser access](/README.md#direct-access-recommended)
* [Local front-end](/README.md#local-front-end-deployment)
* [Docker](/README.md#docker-setup)
* [Flask](/README.md#flask-server)

### Direct Access (Recommended)

Access AVAT via https://aifarms.github.io/AVAT/.

#### Browser Support

AVAT supports the following browsers:

- Chrome 49 (release: 2/3/2016)
- Firefox 50 (release: 11/15/2016)
- Safari 10 (release: 9/20/2016)
- Edge 14 (release: 2/18/2016)

If you encounter any errors, we recommend using the latest version of Chrome or Firefox.

### Local Front-end Deployment

These instructions allow you to deploy a copy of the project running on your local device.

#### Prerequisites

You will need the following tooling to deploy AVAT:

* npm
* A [compatible web browser](/README.md#browser-support
* Git

#### Installing and Building

1. First, clone the repository to your desired location:

```
git clone https://github.com/AIFARMS/pig-annotation-tool
```

Secondly, you will need to install the node_modules which can be done by:
2. Install the node_modules:

```
npm install
```
Lastly, run start to get the project running on your local machine. The website will be on http://localhost:4000/
This is for the front-end portion of the dashboard. Currently, there is no backend portion to this website.

3. Run `npm start` to get the project running on your local machine. The website will be on http://localhost:4000/

```
npm start
```

If the goal is to simply access the website, then go to the ```build``` folder to ```index.html``` to access the website.
This is for the front-end portion of the dashboard. Currently, there is no back-end portion to this website.

If the goal is to only access the website, then go to ```build > index.html``` in this repository.

## Docker setup
### Docker Setup

Currently docker is setup to run the the node project. This will be further expanded onto in the future to include Clowder integration, backend servers, etc
Currently Docker is set up to run the the node project. This will be expanded in the future to include Clowder integration, backend servers, etc.

*These commands are written for a UNIX based machine running Docker. Support for windows is uncertain*
> [!NOTE]
> These commands are written for a Unix-based machine running Docker. Support for Windows is uncertain at this time.

Easy command list:
- To build and run docker container
Expand All @@ -50,17 +87,22 @@ Easy command list:
- To remove pre-existing container and build new container
```sudo docker stop avat && sudo docker rm avat && sudo docker build --tag avat:latest . && sudo docker run -it --rm -v ${PWD}:/avat -v /AVAT/node_modules -e CHOKIDAR_USEPOLLING=true --name avat -p 3001:3000 avat && sudo docker start avat && sudo docker ps -a | grep avat```

## Flask server
### Flask Server

> [!NOTE]
> This section can be further expanded on to include any external models as needed.
Comment on lines +92 to +93
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what the purpose of this is


> [!NOTE]
> These commands are written for a Unix-based machine running Docker. Support for Windows is uncertain at this time.

There is also support for running this off of a flask server. This will be further expanded on into the future to include any external models and such.
Set up a virtual environment and install the proper dependencies from ```backend/requirements.txt```. Then change current directory to ```backend``` and type in ```flask run```. The website should be up on ```http://127.0.0.1:5000```

*These commands are written for a UNIX based machine running Docker. Support for windows is uncertain*
## Getting Started with AVAT

Setup a virtual environment and install the proper dependencies from ```backend/requirements.txt```. Then change current directory to ```backend``` and type in ```flask run```. The website should be up on ```http://127.0.0.1:5000```
After successfully deploying AVAT, please refer to our [Getting Started with AVAT](https://github.com/AIFARMS/AVAT/blob/master/USAGE.md) doc for a detailed guide on using the platform.

## Built With

### FrontEnd
* [React](https://reactjs.org/) - Main Front-End Framework
* [React Bootstrap](https://react-bootstrap.github.io/) - UI Library
* [react-player](https://www.npmjs.com/package/react-player) - Video Player
Expand Down
44 changes: 2 additions & 42 deletions USAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,6 @@
# Instructions for Using the AVAT Platform
# Getting Started with AVAT

The AVAT platform is designed to be accessible for users across various academic disciplines, providing a robust interface for efficient video annotation. This document outlines the key features of the platform, including user interface details, key bindings, and the process for uploading media and annotating videos.

For a system that spans multiple academic disciplines, ensuring a robust interface allows a person of any experience to efficiently annotate videos. A potential user should be able to identify animals of interest easily and have a method to track them across frames in an easy and efficient manner. For a more efficient workflow, a series of key bindings was implemented to expedite each operation within the platform, therefore allowing unexperienced users to familiarize themselves with a predetermined workflow efficiently.

## Overview

AVAT aims to simplify the video annotation process, allowing users to easily identify and track animals of interest across frames. A significant challenge addressed was conditioning users to adopt a predetermined workflow for increased efficiency, even without prior intensive training on our system.

## Browser Support

The following browsers are supported by the AVAT platform. If you encounter any errors, we recommend using the latest version of Chrome or Firefox, as these have been extensively tested:

- Chrome 49 (release: 2/3/2016)
- Firefox 50 (release: 11/15/2016)
- Safari 10 (release: 9/20/2016)
- Edge 14 (release: 2/18/2016)

## Direct Access (Recommended)

Access AVAT via https://aifarms.github.io/AVAT/.

## Local Deployment (Frontend)

These instructions will help you set up a local copy of the project for development and testing purposes.

### Prerequisites

You will need to have npm, firefox/chrome, and git installed on your system.

### Installing and Building

1. Clone the repository to your desired location:
```bash
git clone https://github.com/AIFARMS/AVAT
2. Install the required node_modules:
```bash
npm install
3. Start the project locally. The website will be accessible at http://localhost:4000/. This command starts the front-end portion of the dashboard:
```bash
npm start
4. To simply access the website, navigate to the build folder and open `index.html`.
This guide will show you how to use AVAT's front-end functionality.

## Key Bindings

Expand Down