Annotate-Lab

Annotate-Lab is an open-source application designed for image annotation, comprising two main components: the client and the server. The client, a React application, is responsible for the user interface where users perform annotations. On the other hand, the server, a Flask application, manages persisting the annotated changes and generating masked and annotated images, along with configuration settings. More information can be found in our documentation.

Demo [V1.0]

Table of Contents

• Project Structure
• Dependencies
• Setup and Installation
• Running the Application
• Running Tests
  • Client Tests
  • Server Tests
• Usage
• Outputs
• Troubleshooting
• Contributing
• License

Project Structure [documentation page]

annotation-lab/
├── client/
│   ├── public/
│   ├── src/
│   ├── package.json
│   ├── package-lock.json
│   └── ... (other React app files)
├── server/
│   ├── db/
│   ├── tests/
│   ├── venv/
│   ├── app.py
│   ├── requirements.txt
│   └── ... (other Flask app files)
├── README.md

Client

• public/: Static files and the root HTML file.
• src/: React components and other frontend code.
• package.json: Contains client dependencies and scripts.

Server

• db/: Database-related files and handlers.
• venv/: Python virtual environment (not included in version control).
• tests/: Contains test files.
• app.py: Main Flask application file.
• requirements.txt: Contains server dependencies.

Settings [documentation page]

One can configure the tools, tags, upload images and do many more from the settings.

Dependencies

Client

• React
• Axios
• Other dependencies as listed in package.json

Server

• Flask
• Flask-CORS
• pandas
• Other dependencies as listed in requirements.txt

Setup and Installation [documentation page]

Client Setup

1. Navigate to the client directory:

   cd client

2. Install the dependencies:

   npm install

Server Setup

1. Navigate to the server directory:

   cd server

2. Create and activate a virtual environment:

   python3 -m venv venv
   
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`

3. Install the dependencies:

   pip install -r requirements.txt

Running the Application

Running the Client

1. Navigate to the client directory:

   cd client

2. Install the dependencies:

   npm start

The application should now be running on http://localhost:5173.

Running the Server

1. Navigate to the server directory:

   cd server

2. Activate the virtual environment:

   source venv/bin/activate  # On Windows use `venv\Scripts\activate`

3. Start the Flask application:

   flask run

The server should now be running on http://localhost:5000.

Running using Docker.

Navigate to the root directory and run the following command to start the application:

docker-compose build
docker-compose up -d #running in detached mode

The application should be running on http://localhost.

Running Tests

Client Tests

The client tests are located in the client/src directory and utilize .test.js extensions. They are built using Jest and React Testing Library.

Install Dependencies:

cd client
npm install

Run Tests:

npm test

This command launches the test runner in interactive watch mode. It runs all test files and provides feedback on test results.

Server Tests

The server tests are located in the server/tests directory and are implemented using unittest.

Install Dependencies:

cd ../server
python -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`
pip install -r requirements.txt

Run Tests:

python3 -m unittest discover -s tests -p 'test_*.py'

This command discovers and runs all test files (test_*.py) in the server/tests directory using unittest.

Usage

1. Open your web browser and navigate to http://localhost:5173.
2. Use the user interface to upload and annotate images.
3. The annotations and other interactions will be handled by the Flask server running at http://localhost:5000.

Configurations (Optional) [documentation page]

You can customize various aspects of Annotate-Lab through configuration settings. To do this, modify the config.py file in the server directory or the config.js file in the client directory.

# config.py
MASK_BACKGROUND_COLOR = (0, 0, 0)  # Black background for masks

// config.js
const config = {
    SERVER_URL, // url of server
    UPLOAD_LIMIT: 5, // image upload limit
    OUTLINE_THICKNESS_CONFIG : { // outline thickness of tools
      POLYGON: 2,
      CIRCLE: 2,
      BOUNDING_BOX: 2
    }
  };

Outputs

Sample of annotated image along with its mask and settings is show below.

{
   "configuration":[
      {
         "image-name":"orange.png",
         "regions":[
            {
               "region-id":"47643630436867834",
               "image-src":"http://127.0.0.1:5000/uploads/orange.png",
               "class":"Orange",
               "comment":"",
               "tags":"",
               "points":[
                  [
                     0.4685613390092879,
                     0.7693498452012384
                  ],
                  [
                     0.6781491873065015,
                     0.6640866873065016
                  ],
                  [
                     0.723921246130031,
                     0.5092879256965944
                  ],
                  [
                     0.7480118034055728,
                     0.34055727554179566
                  ],
                  [
                     0.5841960139318886,
                     0.14705882352941177
                  ],
                  [
                     0.41917569659442727,
                     0.13312693498452013
                  ],
                  [
                     0.30113196594427244,
                     0.22755417956656346
                  ],
                  [
                     0.21079237616099072,
                     0.4411764705882353
                  ],
                  [
                     0.26620065789473685,
                     0.6764705882352942
                  ],
                  [
                     0.4011077786377709,
                     0.7879256965944272
                  ]
               ]
            },
            {
               "region-id":"5981359766055432",
               "image-src":"http://127.0.0.1:5000/uploads/orange.png",
               "class":"Apple",
               "comment":"",
               "tags":"",
               "x":[
                  0.1770655959752322
               ],
               "y":[
                  0.11764705882352941
               ],
               "w":[
                  0.5854005417956657
               ],
               "h":[
                  0.6981424148606811
               ]
            }
         ],
         "color-map":{
            "Orange":[
               244,
               67,
               54
            ],
            "Apple":[
               33,
               150,
               243
            ]
         }
      }
   ]
}

Troubleshooting [documentation page]

• Ensure that both the client and server are running.
• Check the browser console and terminal for any errors and troubleshoot accordingly.
• Verify that dependencies are correctly installed.

Contributing

If you would like to contribute to this project, please fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License.

Acknowledgment

This project uses some part of work from idapgroup react-image-annotate and image_annotator.