You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[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 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.
- [Build docker from sources](#build-docker-from-sources)
26
+
*[Contributing](#4-contributing)
27
+
- [Pixano architecture: Pixano-app and Pixano-elements](#pixano-architecture-pixano-app-and-pixano-elements)
28
+
- [Some documentation to get started](#some-documentation-to-get-started)
8
29
9
30
10
-
## 1. Installation & Setup
31
+
## 1. Installation
11
32
12
-
### 1.a) Using Docker Image[recommended]
33
+
### Using Docker Image
13
34
14
35
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.
15
36
16
-
Here's the simplest way you can run the Pixano application using docker, assuming you're familiar with using -v argument to mount folders:
37
+
Here's the simplest way you can run the Pixano application using docker:
17
38
18
39
```bash
19
40
sudo docker run -it --rm -v "$PWD":/data -p 3000:3000 pixano/pixano-app
20
41
```
21
42
22
-
The path where you run this command must contain your folder of images.
43
+
The path where you run this command must contain the data you want to annotate.
44
+
45
+
*NB: This path is defined as your workspace.*
46
+
47
+
#### Optional: create an alias
48
+
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:
23
49
24
-
[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:
25
50
```bash
26
51
# Setup the alias. Put this in your .bashrc file so it's available at startup.
27
52
# Note that the --network host works only on Linux, use explicit port mapping for Windows and Mac
*Update 2020.12.04: Make sure your image extensions are either `png` or `jpg`.
71
-
72
-
*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.
73
-
74
-
### 1.b) Manual Installation [developers]
75
-
76
-
#### Global dependencies
80
+
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.
77
81
78
-
- NodeJS (>=12)
79
-
To install on ubuntu:
80
-
```bash
81
-
# Make sure you have curl installed
82
-
sudo apt install curl
83
-
# Then download and execute the Node.js 10.x installer
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:
92
-
93
-
#### Application dependencies
82
+
#### Install application dependencies
94
83
95
84
```bash
96
-
# Install backend dependencies
97
-
npm i
98
-
# Install frontend dependencies
99
-
cd frontend/
100
-
npm i
85
+
npm run deps
101
86
```
102
87
103
88
##### Using a local pixano-element
@@ -119,7 +104,14 @@ npm run build
119
104
120
105
#### Run the application
121
106
122
-
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.
107
+
In the command prompt, type in `node server/server.js /path/to/your/workspace` from the root folder and hit enter.
108
+
109
+
*NB: Make sure when typing this command that the workspace (`/path/to/your/workspace`) contains all of the data you want to use.*
110
+
111
+
112
+
## 2. Usage
113
+
114
+
After running Pixano-App, you’ll see something similar to this:
Open your browser and hit _http://localhost:3000_. You should see the login page of the application.
136
128
137
-
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.
First authentication is: `username: admin``password: admin`.
139
132
140
-
*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.*
133
+
### Configure your first annotation project
141
134
135
+
Before annotating, configure your project by following our [admin's guide](./admin-guide.md). You will be able to:
142
136
143
-
## 2. Contributing
137
+
- define your datasets
138
+
- define your desired annotation tasks
139
+
- define your users and their role (annotators, validators, administrators)
144
140
145
-
If you want to edit the application to your liking, fork this repository.
141
+
### Start annotating
146
142
147
-
- To get familiar with how the app is built from Web Components, read the [LitElement](https://lit-element.polymer-project.org/) documentation.
148
-
- To get familiar with how the data is managed in the client, read the [redux](https://redux.js.org/introduction/getting-started) documentation.
149
-
- To better understand the Pixano server API, read its [documentation](documentation/rest-api.md)
143
+
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.
144
+
Our [plugins' guide](./plugins-guide.md) will help you in the use of your current task's specific plugin.
150
145
151
-
### Build docker from sources
146
+
### Export your annotations
152
147
153
-
To create a docker image of the application, build the application (step 1.b) and then run:
154
-
```bash
155
-
# You can change `pixano` by your choosen image name
156
-
sudo docker build -t pixano/pixano-app:my-tag .
157
-
# You can use the local Dockerfile if the build folder already exists
Get your annotations and use them for any external application easily:
149
+
150
+
- as an admin, go to the tasks tab
151
+
- press the "EXPORT TO FILES" button
152
+
- you will find the exported annotations in the root of your workspace (find more information on annotation format [bellow](#importexport-annotation-format))
153
+
154
+
### Standalone vs distributed usage
155
+
156
+
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.
157
+
158
+
Pixano-app is also developed to enable a distributed work:
159
+
160
+
- install Pixano-app on a server and open its ip and port to your annotators inside your network
161
+
- define your datasets, tasks and users (See [admin's guide](./admin-guide.md)). The tasks will be automatically distributed between the annotators.
162
+
- each annotator can start working immediately from his computer without installing anything by connecting to _http://xxx.xxx.x.xx:3000_
160
163
161
-
## 3. Import existing annotations / predictions
162
164
163
-
Create an `annotation` folder as such:
165
+
## 3. Advanced usage
166
+
167
+
### Import predictions
168
+
169
+
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).
170
+
171
+
### Import/Export annotation format
172
+
164
173
```
165
174
data-test
166
175
│
@@ -174,4 +183,45 @@ data-test
174
183
│ xxx.json
175
184
└─── yyy.json
176
185
```
177
-
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).
186
+
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).
187
+
188
+
### Build docker from sources
189
+
190
+
To create a docker image of the application, build the application (step 1.b) and then run:
191
+
```bash
192
+
# You can change `pixano` by your choosen image name
193
+
sudo docker build -t pixano/pixano-app:my-tag .
194
+
# You can use the local Dockerfile if the build folder already exists
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).
202
+
203
+
If you want to edit the application to your liking, fork this repository!
204
+
205
+
If you want to contribute more actively to the project, feel free to write your patches or new features and make a pull request!
206
+
207
+
### Pixano architecture: Pixano-app and Pixano-elements
**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)):
212
+
213
+
- the backend manages the data (datasets to be annotated), the tasks (tasks to be performed by annotators) and the users (annotators, validators, admin)
214
+
- the frontend implements the web views and calls the elements through plugins
215
+
- backend and frontend communicate via a REST api
216
+
217
+
[**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.
218
+
219
+
### Some documentation to get started
220
+
- General documentation:
221
+
- To get familiar with how the app is built from Web Components, read the [LitElement](https://lit-element.polymer-project.org/) documentation.
222
+
- To get familiar with how the data is managed in the client, read the [redux](https://redux.js.org/introduction/getting-started) documentation.
223
+
- Pixano's developers documentation
224
+
- To better understand the Pixano server API, read its [documentation](documentation/rest-api.md)
225
+
- 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/)
0 commit comments