Document usage

docs/usage/predict.md

@@ -13,10 +13,11 @@ Use the `teklia-dan predict` command to predict a trained DAN model on an image.
 | `--output`                  | Path to the output folder. Results will be saved in this directory.                          | `Path`  |               |
 | `--scale`                   | Image scaling factor before feeding it to DAN.                                               | `float` | `1.0`         |
 | `--confidence-score`        | Whether to return confidence scores.                                                         | `bool`  | `False`       |
-| `--confidence-score-levels` | Level to return confidence scores. Should be any combination of `["line", "word", "char"]`. | `str`   |               |
+| `--confidence-score-levels` | Level to return confidence scores. Should be any combination of `["line", "word", "char"]`.  | `str`   |               |
 | `--attention-map`           | Whether to plot attention maps.                                                              | `bool`  | `False`       |
 | `--attention-map-scale`     | Image scaling factor before creating the GIF.                                                | `float` | `0.5`         |
 | `--attention-map-level`     | Level to plot the attention maps. Should be in `["line", "word", "char"]`.                   | `str`   | `"line"`      |
+| `--predict-objects`         | Whether to return polygons coordinates.                                                      | `bool`  | `False`      |
 | `--word-separators`         | List of word separators.                                                                     | `list`  | `[" ", "\n"]` |
 | `--line-separators`         | List of line separators.                                                                     | `list`  | `["\n"]`      |
 
@@ -100,3 +101,56 @@ It will create the following JSON file named `dan_humu_page/predict/example.json
 }
 ```
 <img src="../../assets/example_word.gif" >
+
+
+### Predict with line-level attention maps and extract polygons
+
+To run a prediction, plot line-level attention maps, and extract polygons, run this command:
+
+```shell
+teklia-dan predict \
+    --image dan_humu_page/example.jpg \
+    --model dan_humu_page/model.pt \
+    --parameters dan_humu_page/parameters.yml \
+    --charset dan_humu_page/charset.pkl \
+    --output dan_humu_page/predict/ \
+    --scale 0.5 \
+    --attention-map \
+    --predict-objects
+```
+
+It will create the following JSON file named `dan_humu_page/predict/example.json` and a GIF showing a line-level attention map with extracted polygons `dan_humu_page/predict/example_line.gif`
+
+```json
+{
+    "text": "Oslo\n39 \nOresden den 24te Rasser!\nH\u00f8jst\u00e6redesherr Hartvig - asser!\nUllereder fra den f\u00f8rste tide da\njeg havder den tilfredsstillelser at vide den ar-\ndistiske ledelser af Kristiania theater i Deres\nhronder, har jeg g\u00e5t hernede med et stille\nh\u00e5b om fra Dem at modtage et forelag, sig -\nsende tils at lade \"K\u00e6rlighedens \u00abKomedie\u00bb\nopf\u00f8re fore det norske purblikum.\nEt s\u00e5dant forslag er imidlertid, imod\nforventning; ikke fremkommet, og jeg n\u00f8des der-\nfor tils selv at grivbe initiativet, hvilket hervede\nsker, idet jeg\nbeder\nbet\nragte stigkket som ved denne\nskrivelse officielde indleveret til theatret. No-\nget exemplar af bogen vedlagger jeg ikke da\ndenne (i 2den udgave) med Lethed kan er -\nholdet deroppe.\nDe bet\u00e6nkeligheder, jeg i sin tid n\u00e6-\nrede mod stykkets opf\u00f8relse, er for l\u00e6nge si -\ndem forsvundne. Af mange begn er jeg kom-\nmen til den overbevisning at almenlreden\naru har f\u00e5tt sine \u00f8gne opladte for den sand -\nMed at dette arbejde i sin indersten id\u00e9 hviler\np\u00e5 et ubedinget meralsk grundlag, og brad\nstykkets hele kunstneriske struktuve ang\u00e5r,",
+    "objects": [
+        {
+            "confidence": 0.68,
+            "polygon": [
+                [
+                    264,
+                    118
+                ],
+                [
+                    410,
+                    118
+                ],
+                [
+                    410,
+                    185
+                ],
+                [
+                    264,
+                    185
+                ]
+            ],
+            "text": "Oslo",
+            "text_confidence": 0.8
+        },
+        ...
+    "attention_gif": "dan_humu_page/predict/example_line.gif"
+}
+```
+
+<img src="../../assets/example_line_polygon.gif" >