Skip to content

Commit

Permalink
Merge pull request #6 from bbsaclay/master
Browse files Browse the repository at this point in the history 
v0.5.0
  • Loading branch information
@bbsaclay
bbsaclay authored Dec 23, 2021
2 parents 486f435 + 56ad141 commit d88ff99
Show file tree
Hide file tree
Showing 49 changed files with 731 additions and 540 deletions.
12 changes: 8 additions & 4 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
FROM ubuntu:18.04
FROM ubuntu:20.04

# Install Node.js
RUN apt update && apt install -y --reinstall ca-certificates curl build-essential
RUN apt-get update && apt-get install -y --reinstall ca-certificates curl build-essential
RUN curl --silent --location https://deb.nodesource.com/setup_12.x | bash -
RUN apt install -y nodejs && apt install -y python-requests
RUN apt-get install -y nodejs
RUN npm install -g [email protected]

# Copy files for the frontend
Expand All @@ -15,10 +15,14 @@ COPY server server
COPY .logo-ascii .logo-ascii

# Build frontend and install backend dependencies
RUN npm i && cd frontend/ && npm i && npm run build && rm -rf src frontend && cd ..
RUN npm deps && npm run build && rm -rf frontend

EXPOSE 3000

# default files and folders (usefull when no volume can be mounted with this image)
RUN mkdir -p /data


# ENTRYPOINT ["node", "server/server.js"]
RUN echo 'cat .logo-ascii && node server/server.js "$@"' > entrypoint.sh
ENTRYPOINT ["sh", "entrypoint.sh" ]
Expand Down
12 changes: 8 additions & 4 deletions Dockerfile-local
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Build Docker image
FROM ubuntu:18.04
FROM ubuntu:20.04

# Install Node.js
RUN apt-get update && apt-get install -y --reinstall ca-certificates curl build-essential
RUN curl --silent --location https://deb.nodesource.com/setup_10.x | bash -
RUN apt install -y nodejs && apt install -y python-requests
RUN curl --silent --location https://deb.nodesource.com/setup_12.x | bash -
RUN apt-get install -y nodejs
RUN npm install -g [email protected]

# Copy bundled frontend
COPY build build
Expand All @@ -18,6 +18,10 @@ COPY .logo-ascii .logo-ascii
RUN npm install
EXPOSE 3000

# default files and folders (usefull when no volume can be mounted with this image)
RUN mkdir -p /data


# ENTRYPOINT ["node", "server/server.js"]
RUN echo 'cat .logo-ascii && node server/server.js "$@"' > entrypoint.sh
ENTRYPOINT ["sh", "entrypoint.sh" ]
Expand Down
218 changes: 134 additions & 84 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,52 @@
# <img src="frontend/images/pixano_logo.png" alt="Pixano" height="100"/>

[![License](https://img.shields.io/badge/license-CeCILL--C-blue.svg)](LICENSE) [![Live Demo](https://img.shields.io/badge/demo-online-green.svg)](http://pixano.cea.fr/smart-annotation/) [![License](https://img.shields.io/docker/pulls/pixano/pixano-app.svg)](Docker)

## What is PIXANO ?
[Pixano](https://pixano.cea.fr/) is a web-based smart-annotation tool for computer vision applications. The modules are driven by artificial intelligence, which assists the human user with annotation tasks and accelerate the annotation process. Try some of our features [online](https://pixano.github.io/demo/demo.html)!

[![pixano.gif](documentation/pixano.gif)](https://www.youtube.com/watch?v=z5T2HhnugJo)

Pixano App
===============
[![License](https://img.shields.io/badge/license-CeCILL--C-blue.svg)](LICENSE) [![Live Demo](https://img.shields.io/badge/demo-online-green.svg)](http://pixano.cea.fr/smart-annotation/) [![License](https://img.shields.io/docker/pulls/pixano/pixano-app.svg)](Docker)

Pixano App is a web-based annotation tool. It relies on web components dedicated to annotation [pixano-elements](https://github.com/pixano/pixano-elements). This document explains how to run it.
## Table of Contents
* [Installation](#1-installation)
- [Using Docker Image](#using-docker-image)
- [From source (for developers)](#install-from-source-for-developers)
* [Usage](#2-usage)
- [Configure your first annotation project](#configure-your-first-annotation-project)
- [Start annotating](#start-annotating)
- [Export your annotations](#export-your-annotations)
- [Standalone vs distributed usage](#standalone-vs-distributed-usage)
* [Advanced usage](#3-advanced-usage)
- [Import predictions](#import-predictions)
- [Import/Export annotation format](#importexport-annotation-format)
- [Build docker from sources](#build-docker-from-sources)
* [Contributing](#4-contributing)
- [Pixano architecture: Pixano-app and Pixano-elements](#pixano-architecture-pixano-app-and-pixano-elements)
- [Some documentation to get started](#some-documentation-to-get-started)


## 1. Installation & Setup
## 1. Installation

### 1.a) Using Docker Image [recommended]
### Using Docker Image

The easiest way to get up-and-running is to install [Docker](https://www.docker.com/). Then, you should be able to download and run the pre-built image using the docker command line tool. Find out more about the `pixano` image on its [Docker Hub](https://hub.docker.com/r/pixano/pixano-app/) page.

Here's the simplest way you can run the Pixano application using docker, assuming you're familiar with using -v argument to mount folders:
Here's the simplest way you can run the Pixano application using docker:

```bash
sudo docker run -it --rm -v "$PWD":/data -p 3000:3000 pixano/pixano-app
```

The path where you run this command must contain your folder of images.
The path where you run this command must contain the data you want to annotate.

*NB: This path is defined as your workspace.*

#### Optional: create an alias
In practice, we suggest you setup an alias called `pixano` to automatically expose the folder containing your specified image, so the script can read it and store results where you can access them. This is how you can do it in your terminal console on OSX or Linux:

[Optional] In practice, we suggest you setup an alias called `pixano` to automatically expose the folder containing your specified image, so the script can read it and store results where you can access them. This is how you can do it in your terminal console on OSX or Linux:
```bash
# Setup the alias. Put this in your .bashrc file so it's available at startup.
# Note that the --network host works only on Linux, use explicit port mapping for Windows and Mac
Expand All @@ -33,71 +58,31 @@ pixano ./data-test --port 3001
# pixano
```

You’ll see something similar to this.

```bash
┌────────────────────────────────────────────────────────────────────────┐
│ │
│ Serving /path/to/your/workspace │
│ │
│ - Local: http://localhost:3000 │
│ - On Your Network: http://xxx.xxx.x.xx:3000 │
│ │
└────────────────────────────────────────────────────────────────────────┘
```

Open your browser and hit `localhost:3000`. You should see the login page of the application.

![pixano-elements](./frontend/images/login.png)
### Install from source (for developers)

First authentification is: `username: admin` `password: admin`.
#### Install global dependencies

You can then create your annotation project in the `Tasks` tab or update your login in the `Users` tab.
- NodeJS (>=12)
To install on ubuntu:

If your `data-test` folder has the following structure:
```
data-test
│
└───images
│ xxx.jpg
│ yyy.jpg
│
│ ...
```bash
# Make sure you have curl installed
sudo apt install curl
# Then download and execute the Node.js 10.x installer
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
# Once the installer is done doing its thing, you will need to install (or upgrade) Node.js
sudo apt install nodejs
# Make sure the version is now correct
nodejs --version
npm install -g [email protected]
```
You can fill the task configuration as follows, which will create as many annotation jobs as there are images in your `image` folder:
![task-creation](./frontend/images/task-creation.png)

*Update 2020.12.04: Make sure your image extensions are either `png` or `jpg`.

*Update 2021.03.05: Videos are not directly handled: extract the video frames beforehand. For every plugin taking a sequence as input (e.g. `sequence-rectangle`, `sequence-polygon`, `tracking`, etc), each subfolder containing images will be considered as a sequence.

### 1.b) Manual Installation [developers]

#### Global dependencies
You can read this nice [introduction](https://codeburst.io/the-only-nodejs-introduction-youll-ever-need-d969a47ef219) to NodeJS in case you're curious on how it works.

- NodeJS (>=12)
To install on ubuntu:
```bash
# Make sure you have curl installed
sudo apt install curl
# Then download and execute the Node.js 10.x installer
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
# Once the installer is done doing its thing, you will need to install (or upgrade) Node.js
sudo apt install nodejs
# Make sure the version is now correct
nodejs --version
npm install -g [email protected]
```
You can read this nice [introduction](https://codeburst.io/the-only-nodejs-introduction-youll-ever-need-d969a47ef219) to NodeJS in case you're curious on how it works:
#### Application dependencies
#### Install application dependencies

```bash
# Install backend dependencies
npm i
# Install frontend dependencies
cd frontend/
npm i
npm run deps
```

##### Using a local pixano-element
Expand All @@ -119,7 +104,14 @@ npm run build

#### Run the application

In the command prompt, type in `node server/server.js /path/to/workspace/` from the root folder and hit enter. You’ll see something similar to this.
In the command prompt, type in `node server/server.js /path/to/your/workspace` from the root folder and hit enter.

*NB: Make sure when typing this command that the workspace (`/path/to/your/workspace`) contains all of the data you want to use.*


## 2. Usage

After running Pixano-App, you’ll see something similar to this:

```bash
┌────────────────────────────────────────────────────────────────────────┐
Expand All @@ -132,35 +124,52 @@ npm run build
└────────────────────────────────────────────────────────────────────────┘
```

E.g: `node server/server.js ./data-test/`.
Open your browser and hit _http://localhost:3000_. You should see the login page of the application.

Open your browser and hit `localhost:3000`. You should see the login page of the application. First authentification is: `username: admin` `password: admin`. You can then create your annotation project in the `Tasks` tab or update your login in the `Users` tab.
![pixano-elements](./documentation/images/page-login.png)

First authentication is: `username: admin` `password: admin`.

*NB: When creating an annotation task, you will refer to the folder containing the images you want to annotate by a relative path from the `workspace` folder. Make sure when typing `node server/server.js /path/to/workspace/` that it contains all of the data you want to use.*
### Configure your first annotation project

Before annotating, configure your project by following our [admin's guide](./admin-guide.md). You will be able to:

## 2. Contributing
- define your datasets
- define your desired annotation tasks
- define your users and their role (annotators, validators, administrators)

If you want to edit the application to your liking, fork this repository.
### Start annotating

- To get familiar with how the app is built from Web Components, read the [LitElement](https://lit-element.polymer-project.org/) documentation.
- To get familiar with how the data is managed in the client, read the [redux](https://redux.js.org/introduction/getting-started) documentation.
- To better understand the Pixano server API, read its [documentation](documentation/rest-api.md)
Once a task is defined, you (or your annotators) will be able to annotate your dataset. See our [annotator's guide](./annotator-guide.md) for your first steps.
Our [plugins' guide](./plugins-guide.md) will help you in the use of your current task's specific plugin.

### Build docker from sources
### Export your annotations

To create a docker image of the application, build the application (step 1.b) and then run:
```bash
# You can change `pixano` by your choosen image name
sudo docker build -t pixano/pixano-app:my-tag .
# You can use the local Dockerfile if the build folder already exists
sudo docker build -t pixano/pixano-app:my-tag -f Dockerfile-local .
```
Get your annotations and use them for any external application easily:

- as an admin, go to the tasks tab
- press the "EXPORT TO FILES" button
- you will find the exported annotations in the root of your workspace (find more information on annotation format [bellow](#importexport-annotation-format))

### Standalone vs distributed usage

Pixano-app can be used standalone on a single machine. In this case, the "admin" can also directly annotate and validate his datasets. See our [admin's guide](./admin-guide.md) for more details.

Pixano-app is also developed to enable a distributed work:

- install Pixano-app on a server and open its ip and port to your annotators inside your network
- define your datasets, tasks and users (See [admin's guide](./admin-guide.md)). The tasks will be automatically distributed between the annotators.
- each annotator can start working immediately from his computer without installing anything by connecting to _http://xxx.xxx.x.xx:3000_

## 3. Import existing annotations / predictions

Create an `annotation` folder as such:
## 3. Advanced usage

### Import predictions

If you want to analyze predictions from your last detector or use these predictions as a pre-annotation, you can import these predictions as existing annotations by using our [annotation format](#importexport-annotation-format).

### Import/Export annotation format

```
data-test
│
Expand All @@ -174,4 +183,45 @@ data-test
│ xxx.json
└─── yyy.json
```
The `task1.json` file contains global task settings (task type, task categories, image folder, etc) and its correspoding `task1` folder contains an annotation file for each image. To prepare those files check the [import documentation](documentation/import-annotations.md).
The `task1.json` file contains global task settings (task type, task categories, image folder, etc) and its corresponding `task1` folder contains an annotation file for each image. To prepare those files check the [import documentation](documentation/import-annotations.md).

### Build docker from sources

To create a docker image of the application, build the application (step 1.b) and then run:
```bash
# You can change `pixano` by your choosen image name
sudo docker build -t pixano/pixano-app:my-tag .
# You can use the local Dockerfile if the build folder already exists
sudo docker build -t pixano/pixano-app:my-tag -f Dockerfile-local .
```


## 4. Contributing

If you tested Pixano and identified some issues or think some useful features are missing, please open an [issue](https://github.com/pixano/pixano-app/issues).

If you want to edit the application to your liking, fork this repository!

If you want to contribute more actively to the project, feel free to write your patches or new features and make a pull request!

### Pixano architecture: Pixano-app and Pixano-elements

![pixano.gif](documentation/Pixano-app_elements_det.png)

**Pixano-app** is a monorepo built on top of web components dedicated to annotation (developed in a separate repo: [pixano-elements](https://github.com/pixano/pixano-elements)):

- the backend manages the data (datasets to be annotated), the tasks (tasks to be performed by annotators) and the users (annotators, validators, admin)
- the frontend implements the web views and calls the elements through plugins
- backend and frontend communicate via a REST api

[**Pixano-elements**](https://github.com/pixano/pixano-elements) provides a wide set of smart and re-usable web components to build highly customizable image and video annotation tools: 2D and 3D bounding boxes, polygons, segmentation masks, customizable labels, label temporal propagation, etc. **Pixano-app** relies on these web components.

### Some documentation to get started
- General documentation:
- To get familiar with how the app is built from Web Components, read the [LitElement](https://lit-element.polymer-project.org/) documentation.
- To get familiar with how the data is managed in the client, read the [redux](https://redux.js.org/introduction/getting-started) documentation.
- Pixano's developers documentation
- To better understand the Pixano server API, read its [documentation](documentation/rest-api.md)
- To get familiar with Pixano's elements, take a look at its [dedicated repository](https://github.com/pixano/pixano-elements) and [modules documentation](https://pixano.github.io/docs/)


Loading

0 comments on commit d88ff99

Please sign in to comment.