backend- back-end api written in node/express/postgressfrontend- front-end client written in react/redux/webpackjest- unit and integration testsprototypes/- exploratory interaction prototypessample-data- initial sample data from researchersstatic- initial static data for testingapi.md- REST API reference documentation
This project exposes a REST API with the following endpoints:
- get /api/annotations/types
- get /api/annotations/workload
- post /api/annotations
More information available in api.md.
Image Annotator is configured to be deployable on any Ubuntu 16 server. All you need is Ansible 2.2x and root access to your desired target machine.
When orchestrating the official production or staging environments you will need
to submit a PR adding configuration for yourself to ansible/vars/users.yml.
Someone who already has access can provision your account and supply you with
the needed "Vault password" to enable deployment.
The following commands are available:
This will open the secrets file in your default editor. Secret data is managed
by Ansible Vault. All secrets are stored in ansible/vars/secrets.yml.
This will prepare a target machine with all system dependencies needed to
run Image Annotator and grant collaborators access to run deployments. You
will be prompted for both a Vault password and a SUDO password during this
task. You will have configured your sudo password at the beginning of the
project when you added yourself to ansible/vars/users.yml.
This will clone your desired commit to the target machine, install all node dependencies, compile the site with webpack, apply any outstanding migrations to the database and restart the API server.
The database residing on the production server is backed up to S3 hourly. Running this for any target server will completely replace the database with the most recent backup. Take care not to do this for production unless you know what you are doing!
The front end is running React, Redux, Webpack.
Run npm install to install all front-end dependencies; then run npm start to launch the webpack dev server. The application will then be available at localhost:8080.
The front end currently needs the local node/postgres backend running (installation instructions below).
These commands are available after installation within the image-annotator/ directory:
npm test: run unit tests with Jest, then lint on exitnpm run lint: run ESLint to identify syntax & style issues in the codenpm run build: generate a static build intoimage-annotator/distnpm run storybook: launch React Storybook for component development (accessible at localhost:6006 by default)
The backend is running node, PostgreSQL and an express based set of middlewares for the REST API we expose. In order to develop the application, you must have an installation of PostgreSQL.
There are numerous ways to run PostgreSQL. Choose the one that is most familiar to you!
If you have Docker on your machine, do the following:
docker run --name ia-pg -d -p 5432:5432 -i postgres
docker exec -it ia-pg su postgres -c 'CREATEDB image-annotator'
npm run migrate:up
npm start
# stop postgres
docker stop ia-pg
# start postgres
docker start ia-pg
If you have VirtualBox and Vagrant on your machine, do the following:
printf "PGHOST=10.10.0.100\nPGUSER=image-annotator" > .env
vagrant up
npm run provision:vagrant
npm run migrate:up
npm start
# stop postgres
vagrant halt
# start postgres
vagrant up
If you want to install PostgreSQL locally on Ubuntu, do the following:
sudo apt-get install postgresql
sudo service postgresql stop
sudo sh -c "printf 'local all all trust\nhost all all 127.0.0.1/32 trust\nhost all all ::1/128 trust' > /etc/postgresql/9.5/main/pg_hba.conf"
sudo service postgresql start
createdb -U postgres image-annotator
npm run migrate:up
npm start
# stop postgres
sudo service postgresql stop
# start postgres
sudo service postgresql start
If you want to install PostgreSQL locally on OSX, do the following:
Ensure you have brew installed. Then, run this:
printf "PGUSER=$USER" > .env
brew install postgresql
brew services start postgresql
createdb image-annotator
npm run migrate:up
npm start
# stop postgres
brew services stop postgresql
# start postgres
brew services start postgresql
cd into the prototypes directory you want to look at and run npm start (Requires python, equivalent to running python -m SimpleHTTPServer 8000) or a comparable static web server.
Navigate to the following prototypes in your browser:
- test on 25 sample landmarked images of faces sample-data-rotate-regions
- UI experiment for three annotation modes: general fabric.js test
This section clarifies the verbiage and terms used within the application code.
An attribute is the object representing a specific type of annotation a user will apply to any given image, such as demographic attributes like "perceived ethnicity" or positional values like "the location of the right eye."
Attribute properties:
- Name: the human-oriented label of an attribute, such as "Perceived Gender."
- Type: the type of data represented by the attribute, e.g. a list of multiple-choice options, or a set of coordinates, etc. Note: This is a database- / data model-oriented value, and has no inherent correspondence to front-end presentation.
- Options: the list of accepted values for a multiple-choice image attribute.
Attribute objects have the shape
{
"name": "Attribute Name",
"type": "type-of-data",
"options": ["list", "of", "accepted", "values", "for", "multiple", "choice", "attributes"]
}An annotation is the object representing the submitted value for a particular Attribute.
Annotation properties:
- Name: the name of the image attribute annotated, such as "Perceived Ethnicity".
- Value: the value with which the image is annotated, such as "Asian" or "Black."
Annotation objects have the shape
{
"name": "Attribute Name",
"value": "selected-value"
}An image annotation is an object associating one or more Annotations with the specific Image to which they were applied. It contains an array of annotations, and the ID of their associated image.
ImageAnnotation objects have the shape:
{
"id": 3359,
"annotations": [{
"name": "Attribute Name",
"value": "selected-value"
}, {
"name": "Another Attribute Name",
"value": "selected-value"
}]
}An image is a representation of an image to which Annotations will be applied.
Image objects have the shape:
{
"id": 3359,
"url": "http://www.url.com/some-image.jpg",
"width": 250,
"height": 250
}A workload is an object containing a list of Images to be annotated.
Workload objects have the shape:
{
"id": 121,
"images": [{
"id": 3359,
"url": "http://url.com/some-image.jpg",
"width": 250,
"height": 250
}, {
"id": 3360,
"url": "http://url.com/other-image.jpg",
"width": 250,
"height": 250
}]
}An annotated workload is a collection of ImageAnnotations submitted for a specific Workload.
Annotated Workload objects have the shape
{
"workloadId": 121,
"images": [{
"id": 3359,
"annotations": [{
"name": "Attribute Name",
"value": "selected-value"
}, {
"name": "Another Attribute Name",
"value": "selected-value"
}]
}, {
"id": 3360,
"annotations": [{
"name": "Attribute Name",
"value": "selected-value"
}, {
"name": "Another Attribute Name",
"value": "selected-value"
}]
}]
}