# Floorplan labeling tool


## How to install

The tool is at [floorplan-labeler.zip](https://drive.google.com/file/d/1nYN4AMnTTUIcPRSseZkAEDKtJY42M71r/view?usp=sharing).

1. We recommand you to use [Anaconda](https://www.anaconda.com/products/individual) to create the environment. Then, you can setup the environnment with:

    conda env create -n floorplan_label

And directly run to install the packages.

    pip install -r requirement.txt

#### Requirements
* python >= 3.7
* PyQt5
* numpy
* plyfile
* opencv-python

2. Please install MeshLab for further visualization. You can find the install package [here](https://www.meshlab.net/#download).

## How to run and use?

python app.py PLY_DATA_DIR OUTPUT_DIR

This will read all `.ply` files in `PLY_DATA_DIR`.
Currently, the output annotation will be saved as `[SCENE_NAME].json` in `OUTPUT_DIR` where `SCENE_NAME` is the name of the `.ply` file.

For example, if you want to label scene `1LXtFkjw3qL`:

python app.py ./pointcloud/1LXtFkjw3qL ./annotation/

1. Left-click the point cloud to label corners. Right-click undo the labeling
2. `W`, `A`, `S`, `D` to move point cloud
3. `E`, `R` to rotate point cloud
4. Scroll to zoom in and out
5. Click `room` or `axis` button on bottom right to switch labeling mode
6. Click `save` button to save result
7. `P`: previous scene. `N`: next scene
8. The bottom panel shows the height for the two slice. Users can adjust the values to view the different slice from the projection. The thickness for each slice is set as 0.1 as default.

## Description for labeling
For labeling a scene, please read carefully the following rules and guides.

1. Furnitures (e.g., closet, cabinet) are not considered as walls.

3. The shape of a room is important for us. Chanfers, sloping-walls, and any details matters. Cosider the follow figures.

4. Rounded-rooms or curvy walls can be represented by multiple corners. As a thumb rule, use a corner distance similar to the sourounding area; not too small, neither too large.

6. Hallways, corridors, and long rooms are tricky scenes. Conisider a large hallway as ONE room only if there is not big change in the room's shape or in its direction. For large scene, consider the provided information to verify the continuity, usually a single large-block is preferred.

5. As the general rule, for any scene, a room is consider as a closed-space region, therefore WE WANT TO LABEL THAT CLOSED-SPACE WITHOUT SPLITTING OR DECOMPOSING IN SMALL PIECES. For instance, the following left image could be considered as two seperate rooms, However, we prefer an unique label room.

6. Doors, small corridores, and conexions between rooms must be ommited to represent properly our label target, rooms.

7. Please refer to this [slides](https://docs.google.com/presentation/d/1EL3yg8xKkhp4fKYPcDIYROwBQ-TC2BDWXo79Uh75vrk/edit#slide=id.ge4a2cd7065_0_0), which contains:
- environment reference: not precise enough, but good reference though.
- point cloud top view from SLAM
- plane reconstruction

7. ### You have 2 things to label:
- ### <strong style="color: red;">rooms</strong>, as mentioned above;
- ### <strong style="color: red;">axis corners</strong>, two corners which are able to form a line that aligns the floorplan when its parrallel to x-axis.


Before Alignment | After Alignment
-|-
 | 

8. If you have any other question, please feel free to ask us, we will add it here.

### Scenes are listed in **[Scene List](https://docs.google.com/spreadsheets/d/1kjsvKFMeddcGMNlxcojl_eSBumXRXoqzrwq8gJaqDYk/edit#gid=0)**, avalible scenes are in <strong style="color: green;">green</strong>, while unavalible scenes are in <strong style="color: red;">red</strong>.

### Aftrer finishing the label, please upload the *.json to the [`annotation`](https://drive.google.com/drive/folders/1rRJHaxsbtsKh7Se-yenR4h0MFLDcPgBT?usp=sharing) folder and fill the blank of the scene you have labeled in **[Scene List](https://docs.google.com/spreadsheets/d/1kjsvKFMeddcGMNlxcojl_eSBumXRXoqzrwq8gJaqDYk/edit#gid=0)**.

### <strong style="color: red;">Your labeling will be checked by @Kike. He will give you some feedbacks on it. A scene will be finished once he approved.</strong>

Google Drive Folder is at [here](https://drive.google.com/drive/u/0/folders/1l9QUl9cgzAmzRQjeo7CDkGs6TJWaRJeq), file structure is shown below:

.
├── annotation
│   ├── scene1.json
│   ├── scene2.json
│   ├── scene3.json
│   └── ...
│
├── pointcloud
│   ├── scene1
│   │   └── scene1.ply
│   ├── scene2
│   │   └── scene2.ply
│   ├── scene3
│   │   └── scene3.ply
│   └── ...
├── floorplan-labeler.zip
│
└── Scene List

## Contact
Please contact to [Justin](mailto:[e-mail]) or [Kike](mailto:[e-mail]).