Banksy annotation tool README

--- title: Banksy annotation tool README tags: aboutgoods --- # Banksy annotation tool ## 📃 Description Banksy is an image annotation tool, outputting a dataset with NER (Named Entity Recognition), NEL (Named Entity Linking) and box region on image. The dataset format is very similar to the [FUNSD dataset](https://guillaumejaume.github.io/FUNSD/). This tool is useful if you need to annotate documents where the spatial component (**where** the text is in the document) of the text data is important. Practical examples might be forms, receipts, etc. You can also find a Python Google Vision OCR client you can call with the image you want to annotate, and will return you a JSON file with position of text found in the image, with the content in it. You can then add the JSON file to your `source` folder (see the Usage section below) and will create automatically boxes for you. You can learn more about the Python client [here](). //TODO : Add the link to the python client readme ## 🔧 Getting Started ### Requirements - NPM (to serve the files, but you can use any other tool to do it) - Chrome (The tool only works on chrome, as it uses modules and Webpack isn't in the project) ### Installation Clone this project ``` git clone ... ``` //TODO: Add the link to the project In order to serve the files, you can use the `serve` package from NPM : ``` npm install -g serve ``` ### Launch To launch the tool, you simply need to serve the files, so you can use `serve` *In the project repository :* ``` serve ``` Or if you want to specify the port : ``` serve -l 8080 ``` ## Usage First you need to add images in the `source` folder. The images needs to be named like `receipt_000.jpg`, `receipt_001.jpg`, ... You can also add Google Vision results for each image like so : `receipt_000.json`, `receipt_001.json`, ... You can now go access to the app (http://localhost:5000 if you used `serve`) ### Creating/Managing boxes When you go to the app, the first image is shown, and you can start drawing boxes by holding the left mouse click. You can undo / redo any action you do by pressing `Ctrl + Z` (or `Cmd + Z`) and `Ctrl + Maj + Z` (or `Cmd + Maj + Z`) You can also merge boxes, by clicking the `Merging mode` button on the bottom. You will now be able to select multiple boxes by drag-clicking on the image. Once you have selected the right boxes, you can merge them by pressing `m`. On the right side, you can see a list of the boxes you created, and can change the content, the type, modify or delete the NELs and delete the box. When you select a box, its corresponding element in the list is highlighted. You can also delete a box with the `del` key. ### Links In order to create links between boxes, select the box that will be the starting point of the link, then click and hold the blue square on the right, and drop the link on the desired destination box. ### Utils You can zoom in and out with the mouse wheel, and move in the receipt by maintaining the `Ctrl` or `Cmd` key. When you finish the annotation of an image, simply hit "Save output" on the top of the screen. A JSON file with all the data will be downloaded. You can then go to the next receipt by clicking on the next button, on the top right, or go back with the previous button. Your work will be saved in local storage. ## Contributing //TODO: To put in contributing file Every contributions are welcome ! Feel free to create issues, add documentation or features to the project ! To make Banksy an awesome project, we need you to respect some guidelines :straight_ruler: - Every issue needs to be detailed. If it's about a bug, don't just say "*this doesn't work !*". Describe your problem, and if possible, tell how to reproduce it. If the issue is about adding a functionality, describe in detail what you want to be added, so that the person(s) assigned to this issue can develop it in the best way possible. - When submitting a pull request that changes the code of the application, make sure that it's well documented, both by documenting the functionalities that you added, and by commenting your code (every part that is a little tricky needs to be documented, and there is never too much documentation !). - We love nice and beautiful code, so please follow the coding best practices. - Commit with explicit messages, so that we know exactly what you did without looking everywhere in your code. Thank you :raised_hands: ## License //TODO: To put in license file Copyright (c) 2020 AboutGoods Company Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.