Notebook annoté.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "toc": true
   },
   "source": [
    "<h1>Table of Contents<span class=\"tocSkip\"></span></h1>\n",
    "<div class=\"toc\"><ul class=\"toc-item\"><li><span><a href=\"#Avant-propos\" data-toc-modified-id=\"Avant-propos-1\"><span class=\"toc-item-num\">1&nbsp;&nbsp;</span>Avant-propos</a></span></li><li><span><a href=\"#Chargment-de-la-configuration\" data-toc-modified-id=\"Chargment-de-la-configuration-2\"><span class=\"toc-item-num\">2&nbsp;&nbsp;</span>Chargment de la configuration</a></span></li><li><span><a href=\"#Téléchargement-des-données\" data-toc-modified-id=\"Téléchargement-des-données-3\"><span class=\"toc-item-num\">3&nbsp;&nbsp;</span>Téléchargement des données</a></span></li><li><span><a href=\"#Classification-des-images\" data-toc-modified-id=\"Classification-des-images-4\"><span class=\"toc-item-num\">4&nbsp;&nbsp;</span>Classification des images</a></span><ul class=\"toc-item\"><li><span><a href=\"#Entraînement\" data-toc-modified-id=\"Entraînement-4.1\"><span class=\"toc-item-num\">4.1&nbsp;&nbsp;</span>Entraînement</a></span></li><li><span><a href=\"#Performances-de-la-classification\" data-toc-modified-id=\"Performances-de-la-classification-4.2\"><span class=\"toc-item-num\">4.2&nbsp;&nbsp;</span>Performances de la classification</a></span></li><li><span><a href=\"#Classification-du-dataset\" data-toc-modified-id=\"Classification-du-dataset-4.3\"><span class=\"toc-item-num\">4.3&nbsp;&nbsp;</span>Classification du dataset</a></span></li></ul></li><li><span><a href=\"#Segmentation-des-catalogues\" data-toc-modified-id=\"Segmentation-des-catalogues-5\"><span class=\"toc-item-num\">5&nbsp;&nbsp;</span>Segmentation des catalogues</a></span><ul class=\"toc-item\"><li><span><a href=\"#Préparation-des-annotations\" data-toc-modified-id=\"Préparation-des-annotations-5.1\"><span class=\"toc-item-num\">5.1&nbsp;&nbsp;</span>Préparation des annotations</a></span></li><li><span><a href=\"#dhSegment\" data-toc-modified-id=\"dhSegment-5.2\"><span class=\"toc-item-num\">5.2&nbsp;&nbsp;</span>dhSegment</a></span></li><li><span><a href=\"#Tensorflow-Object-Detection-API-(TODA)\" data-toc-modified-id=\"Tensorflow-Object-Detection-API-(TODA)-5.3\"><span class=\"toc-item-num\">5.3&nbsp;&nbsp;</span>Tensorflow Object Detection API (TODA)</a></span></li><li><span><a href=\"#Optimisation-des-hyper-paramètres\" data-toc-modified-id=\"Optimisation-des-hyper-paramètres-5.4\"><span class=\"toc-item-num\">5.4&nbsp;&nbsp;</span>Optimisation des hyper-paramètres</a></span><ul class=\"toc-item\"><li><span><a href=\"#Post-processing-dhSegment\" data-toc-modified-id=\"Post-processing-dhSegment-5.4.1\"><span class=\"toc-item-num\">5.4.1&nbsp;&nbsp;</span>Post-processing dhSegment</a></span></li><li><span><a href=\"#Post-processing-Tensorflow-object-detection-API\" data-toc-modified-id=\"Post-processing-Tensorflow-object-detection-API-5.4.2\"><span class=\"toc-item-num\">5.4.2&nbsp;&nbsp;</span>Post-processing Tensorflow object detection API</a></span></li></ul></li><li><span><a href=\"#Performance-de-la-segmentation\" data-toc-modified-id=\"Performance-de-la-segmentation-5.5\"><span class=\"toc-item-num\">5.5&nbsp;&nbsp;</span>Performance de la segmentation</a></span></li><li><span><a href=\"#Segmentation-du-dataset\" data-toc-modified-id=\"Segmentation-du-dataset-5.6\"><span class=\"toc-item-num\">5.6&nbsp;&nbsp;</span>Segmentation du dataset</a></span></li></ul></li><li><span><a href=\"#Base-de-données\" data-toc-modified-id=\"Base-de-données-6\"><span class=\"toc-item-num\">6&nbsp;&nbsp;</span>Base de données</a></span><ul class=\"toc-item\"><li><span><a href=\"#Extraction-du-contenu-des-pages\" data-toc-modified-id=\"Extraction-du-contenu-des-pages-6.1\"><span class=\"toc-item-num\">6.1&nbsp;&nbsp;</span>Extraction du contenu des pages</a></span></li><li><span><a href=\"#Prépartion-des-données-pour-sql\" data-toc-modified-id=\"Prépartion-des-données-pour-sql-6.2\"><span class=\"toc-item-num\">6.2&nbsp;&nbsp;</span>Prépartion des données pour sql</a></span></li><li><span><a href=\"#Importation-des-données-dans-une-base-mysql\" data-toc-modified-id=\"Importation-des-données-dans-une-base-mysql-6.3\"><span class=\"toc-item-num\">6.3&nbsp;&nbsp;</span>Importation des données dans une base mysql</a></span></li></ul></li></ul></div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Avant-propos\n",
    "\n",
    "Ce notebook explique les différentes étapes de la pipeline créée dans le cadre d'un stage réalisé à l'Institut national d'histoire de l'art (INHA) ayant pour but d'extraire des informations structurées de catalogues de vente édités entre le 1er janvier 1939 et le 31 décembre 1945 par la maison de vente Drouot.\n",
    "\n",
    "Ce notebook a plus un but éducatif et donc explicatif que de réellement servir à segmenter plus de documents. Pour segmenter plus de documents, il est plus judicieux de passer directement par les fichiers pythons, tel que le fichier ```main.py``` qui au final lance-lui même les différentes étapes décrites dans ce document."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Chargment de la configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ce notebook ne lit pas le fichier ```config.toml``` présent à la racine du répertoire. Les principales configurations sont faites directement dans le notebook, toutefois il existe plus d'éléments qui peuvent être configurés, mais ceci n'est pas détaillé dans ce notebook.\n",
    "\n",
    "À noter que le fichier de configuration est lu par le fichier ```main.py``` et doit être utilisé conjointement avec celui-ci.\n",
    "\n",
    "Dans le code suivant, on charge la configuration par défaut en lui donnant comme dossier à utiliser ```./test``` ainsi qu'un chemin optionnel vers l'endroit où stocker les images."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from config import load_default_config\n",
    "\n",
    "base_folder = './test'\n",
    "\n",
    "config = load_default_config(base_folder)\n",
    "config['base_folder'] = base_folder\n",
    "config['images_folder'] = '/path/to/drouot/images'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Téléchargement des données"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Code pour télécharger les données depuis l'interface OAI-PMH de la bibliothèque numérique, les catalogues de ventes sont disponibles dans le set ```oai:sets:16800```.\n",
    "\n",
    "Le code va télécharger toutes les métadonnées du set, et les sauver brutes dans un fichier ```inha_bib_num_metadata.json.gz```, le code va également télécharger toutes les métadonées iiif correspondantes pour également tout le set, vu que les informations de date et lieu sont mieux formatées dans ces dernières et va sauver ces informations dans le fichier ```iiif_manifests.json.gz```. Ces deux fichiers sont les portes d'entrées pour la collection et permettent de télécharger les fichiers d'images ainsi que d'obtenir toutes les métadonnées des catalogues de ventes.\n",
    "\n",
    "Cette collection globale et les identifiants qui leur sont propres sont ensuite \"mappé\" vers une numérotation interne pour plus d'uniformité, les liens pour passer de l'un à l'autre se font aux travers de deux fichiers eux aussi sauvegardé sous la forme de jsons:\n",
    "- ```idx2inhaIdx.json``` qui convertit de l'identifiant interne vers l'identifiant numérique unique de la bibliothèque numérique\n",
    "- ```idx2cote.json``` qui convertit de l'identifiant interne vers la côte de la bibliothèque\n",
    "\n",
    "Ces données sont plus ou moins fixes, mais changent à chaque fois que de nouveaux documents sont publiés sur la biblothèque numérique.\n",
    "\n",
    "Un choix a été fait de ne se concentrer que sur la période 1939-1945 et sur la maison de vente Drouot afin d'avoir des documents relativement uniformes dans leur mise en page et un nombre relativement petit (1911 catalogues de vente). Ce choix est directement présent dans le code et n'offre pas d'options de configuration pour le changer.\n",
    "\n",
    "Les métadonées sont donc filtrées pour le sous-set mentionné plus haut et les images sont automatiquement téléchargées avec comme convention de nommage six chiffres d'identifiant unique et six chiffres de pages. Donc par exemple pour la page 15 du document 1754, le fichier est ```001754_000014.jpg``` (14 car la numérotation commence à 0). Le nombre d'image avec ce filtre est d'environ 40'000 pour 1911 catalogues."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from data_downloader.downloading_data import downloading_data\n",
    "downloading_data(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "La numérisation des images n’étant pas consistante, certains des images de catalogues contiennent deux pages et d’autre qu’une seule. Afin d'éviter toute erreur de classification à cause de cette spécificité, les images ont été triées à la main (après une pré-classification réalisée avec des heuristiques simples). Ce choix a été fait car le temps pour trier les 40’000 pages était relativement court (environ 2 heures).\n",
    "\n",
    "Les images qui contenaient deux pages ont ensuite simplement été coupées en deux, car la numérisation était bien alignée.\n",
    "\n",
    "Il faut donc créer un fichier qui contient le chemin absolu vers les fichiers qui contiennent des pages doubles. Le code va ensuite couper ces images en deux et supprimer (!!!) l'original.\n",
    "\n",
    "Si une image est coupée en deux, elle devient donc deux images avec le suffixe ```l``` si c'est l'image de gauche et ```r``` si c'est l'image de droite."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from data_downloader.cutting_pages import cutting_pages\n",
    "\n",
    "config['data']['two_pages_path'] = 'path/to/two_pages_files.txt'\n",
    "\n",
    "cutting_pages(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Classification des images"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Les pages de catalogues sont classifiées en quatre typologies:\n",
    "- **Information de vente** (```sale_information```) qui correspond à une page de garde qui contient toutes les informations relatives à la vente (date, lieu, contenue, expert, commissaire, etc.).\n",
    "- **Description d’objets** (```objects_description```) qui correspond aux pages contenant les objets mis en vente.\n",
    "- **Illustration** (```illustration```) qui correspond aux pages contenant des illustrations des objets mis en vente.\n",
    "- **Autre** (```other```) qui correspond à toutes les autres pages.\n",
    "\n",
    "Ces quatre typologie est un choix fait afin d'avoir à la fois une assez grande diversité visuelle pour que le classifier soit capable de distinguer entre les différentes classes et en même temps de pouvoir avoir la plupart des informations capitales pour un catalogue de vente à portée de main:\n",
    "- Où sont les métadonnées de la vente ?\n",
    "- Où sont les objets ?\n",
    "- Où sont les éventuelles illustrations des ces objets ?\n",
    "\n",
    "Environ 4’500 images ont été classifiées à la main. Plusieurs modèles de classification à base de CNN ont été testé avec plus ou moins de succès.\n",
    "\n",
    "Le modèle qui a été retenu est un modèle basé sur un VGG16 pré-entraîné sur imagenet et qui utilise comme information le numéro de la page. Il a été entraîné sur un set de donnée de 3600 images et testé sur 900. Vu que le nombre d'exemple par classe est différent (majorité de descriptions d'objets), les données d'entraînement ont été sur-échantillonées afin de montrer un nombre égal d'image de chaque classe."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Entraînement\n",
    "Les détails d'implémentations de l'entraînement ne sont pas montrés ici. Le code a toutefois besoin d'un certain nombre d'images déjà annotées pour s'entraîner. Le format est un csv avec une colonne qui contient le nom de base de l'image (sans le chemin) et une deuxième colonne qui contient la classe (comme indiqué plus haut)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 145,
   "metadata": {},
   "outputs": [],
   "source": [
    "from classification.train import train\n",
    "config['classification']['classification_csv'] = './classified_images.csv'\n",
    "train(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Performances de la classification"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Le code suivant montre la [matrice de confusion](https://fr.wikipedia.org/wiki/Matrice_de_confusion) du meilleur classifier.\n",
    "\n",
    "Différents modèles ont été testés (VGG16, Resnet-50, Inception-Resnet V2) et on tous donnée des résultats similaires et très satisfaisant. Le choix du modèle s'est donc fait pour avoir un modèle plus stable avec moins de couches et qui donnait les meilleurs résultats sur les descriptions d'objets. En effet, les erreurs sur cette classe sont les plus pénalisantes, car c'est ce résultat-là de la classification qui va se propager dans les étapes suivantes. Toute page manquée provoquera un manque d'objets et toute page ajoutée ajoutera du bruit au résultat final.\n",
    "\n",
    "Avec le VGG16, nous pouvons donc voir qu'il y a très très peu d'erreurs et très peu de descriptions d'objets sont perdues (0.2%)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 720x576 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "import seaborn as sns\n",
    "\n",
    "confusion_matrix = [[177,   0,   1,   0],\n",
    "       [  0, 438,   1,   0],\n",
    "       [  1,   2, 156,   1],\n",
    "       [  0,   0,   3,  95]]\n",
    "labels = ['illustration', 'objects_description', 'other', 'sale_information']\n",
    "\n",
    "df_cm = pd.DataFrame(confusion_matrix, index=labels, columns=labels, )\n",
    "fig = plt.figure(figsize=(10,8))\n",
    "try:\n",
    "    heatmap = sns.heatmap(df_cm, annot=True, fmt=\"d\", cmap='Blues')\n",
    "except ValueError:\n",
    "    raise ValueError(\"Confusion matrix values must be integers.\")\n",
    "heatmap.yaxis.set_ticklabels(heatmap.yaxis.get_ticklabels(), rotation=0, ha='right', fontsize=12)\n",
    "heatmap.xaxis.set_ticklabels(heatmap.xaxis.get_ticklabels(), rotation=45, ha='right', fontsize=12)\n",
    "plt.ylabel('True label')\n",
    "plt.xlabel('Predicted label');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Une autre métrique intéressante pour estimer la performance du classifier est de regarder le nombre moyen de page et son écart type pour chaque classe par catalogue de vente:\n",
    "\n",
    "|Classe|Nombre moyen|\n",
    "|---|---|\n",
    "|Description d'objets|$16.9 \\pm 15.08$|\n",
    "|Information de vente|$1.02 \\pm 0.39$|\n",
    "|Illustration|$1.22 \\pm 4.55$|\n",
    "|Autre|$3.23 \\pm 2.2$|\n",
    "\n",
    "Sachant qu'il y a en moyenne $22.37 \\pm 17.88$ pages par catalogue. Les résultats semblent cohérents par rapport à ce que l'on pourrait attendre.\n",
    "- Une grande majorité de descriptions d'objets avec un grand écart type correspondante à la déviation du nombre de page par catalogues.\n",
    "- une seule information de vente par catalogue avec un très petit écart type qui montre que le chiffre reste relativement constant.\n",
    "- environ trois pages \"autres\" (par exemple couverture, dernière page, dos), mais qui varie avec parfois plus de pages vides.\n",
    "- environ une illustration par catalogue, mais avec un grand écart type proportionnelle, ce qui montre que certains catalogues n'auront aucune image et d'autre un très grand nombre.\n",
    "\n",
    "Les statistiques complètes sont présentées ici:\n",
    "\n",
    "|Classe| \tmoyenne |\técart type |\tmin \t|25% \t|50% |\t75% |\tmax|\n",
    "|---|---|---|---|---|---|---|---|\n",
    "|Description d'objets| 16.90|15.08|0.0|10.0|14.0|19.0|185.0 |\n",
    "|Information de vente| 1.02|0.39|0.0|1.0|1.0|1.0|6.0 |\n",
    "|Illustration| 1.22|4.56|0.0|0.0|0.0|0.0|105.0 |\n",
    "|Autre| 3.23|2.21|0.0|3.0|3.0|4.0|39.0 |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Classification du dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Une fois le modèle entraîné ou un modèle déjà entraîné téléchargé, il est possible d'inférer les classes de nouvelles images.\n",
    "\n",
    "Il faut toutefois connaître et paramétrer certaines informations, qui sont explicitées dans les commentaires plus bas."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 147,
   "metadata": {},
   "outputs": [],
   "source": [
    "from classification.classify import classify\n",
    "\n",
    "# Dossier contenant les images à annoter\n",
    "images_folder = config['images_folder']\n",
    "\n",
    "# Information sur le modèle\n",
    "config['classification']['model_checkpoint_path'] = '/path/to/the/model.h5'\n",
    "config['classification']['IMAGE_SIZE'] = (224, 224) # par défaut\n",
    "config['classification']['use_page_num'] = True # par défaut\n",
    "config['classification']['labels_txt_path'] = '/path/to/the/labels.txt' # généré par le code précédant\n",
    "\n",
    "# Annotations manuelles\n",
    "classification_csv = config['classification']['classification_csv']\n",
    "\n",
    "# Csv qui contiendra les prédictions faites par le modèle\n",
    "predicted_classes_csv = config['classification']['predicted_classes_csv']\n",
    "\n",
    "classify(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Segmentation des catalogues"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Une fois les images classifiées, le but de ce projet était de les segmenter afin de pouvoir extraire automatiquement les informations sur les objets mis en vente dans un catalogue.\n",
    "\n",
    "Seules les images de la classe “descriptions d’objets” sont segmentées. Le but est de déterminer **deux** typologies, les **sections** qui sont soit les catégories d’objets (e.g. Tableaux) soit les artistes (e.g. Couture) et les **descriptions des objets** qui contiennent un numéro de référence ainsi que d’autres informations sur l’objet.\n",
    "\n",
    "Le choix de ne prédire que ces deux classes est motivé par les raisons suivantes:\n",
    "- Plus facile d'entraîner et d'évaluer le réseau avec deux classes.\n",
    "- Les deux classes sont tout en haut de la hiérarchie des informations que l'on voudrait pouvoir extraire, par exemple un autre type d'information comme le numéro de référence d'un objet ou encore ses dimensions sont contenues à l'intérieur de la classe descriptions d'objets, ils pourraient donc être extrait soit par des étapes de segmentation successives soit en utilisant directement l'OCR.\n",
    "- Les deux classes ont des typologies visuelles suffisamment différentes pour être distinguée par le réseau. Des tentatives qui utilisaient plus de classes ont été infructueuses, comme par exemple essayer de séparer directement les sections contenant des noms d'auteurs de celles décrivant des catégories d'objets. En effet, elles n'étaient pas visuellement assez différentes.\n",
    "\n",
    "Au total, 500 images ont été annotées pour pouvoir entraîner les deux types de réseaux utilisés, dhSegment et la Tensorflow Object Detection API (TODA).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Préparation des annotations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "La première étape de la segmentation est d'annoter un certain nombre d'images manuellement. Le format d'annotation attendu est celui utilisé par [labelme](https://github.com/wkentaro/labelme) qui crée des fichiers json très simple qui contiennent les annotations.\n",
    "\n",
    "La cellule suivante transforme ces annotations afin d'avoir les données nécessaires pour pouvoir entraîner les deux types de réseaux servant à la segmentation.\n",
    "\n",
    "La première ligne (```prepare_dataset```) sert à séparer les données en training et testing set en utilisant par défaut 20% des données pour le test. Cela va créer deux csv, un pour le training, un pour le testing avec chaque annotation (boîte) sur une seule ligne avec les colonnes suivantes:\n",
    "\n",
    "| filename | width | height | class | xmin | ymin | xmax | ymax | \n",
    "| --- | --- | --- |  --- |  --- |  --- |  --- |  --- |\n",
    "|nom de base du fichier | largeur de l'image | hauteur de l'image | classe de l'annotation | plus petit x de la boîte| plus grand x de la boîte| plus petit y de la boîte | plus grand y de la boîte|\n",
    "\n",
    "La deuxième ligne (```create_masks```) crée les masques utilisés par [dhSegment](https://github.com/dhlab-epfl/dhSegment) pour l'entraînement, elle crée également des csv pointant vers ces masques et les images de bases qui devront être ajoutés dans la configuration de dhSegment.\n",
    "\n",
    "La troisième ligne (```create_tf_dataset```) crée deux fichiers au format TFRecord avec le bon format pour être utilisé avec la [Tensorflow Object Detection API](https://github.com/tensorflow/models/tree/master/research/object_detection) et un fichier pbtxt contenant le mapping nombre vers classe demandé par l'API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 150,
   "metadata": {},
   "outputs": [],
   "source": [
    "from segmentation import prepare_dataset, create_masks, create_tf_dataset\n",
    "\n",
    "config['segmentation']['annotation_directory'] = '/path/to/the/annotations'\n",
    "\n",
    "prepare_dataset.prepare_dataset(config)\n",
    "create_masks.create_masks(config)\n",
    "create_tf_dataset.create_tf_dataset(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### dhSegment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[dhSegment](https://github.com/dhlab-epfl/dhSegment) est un outil développé par le DHlab à l’EPFL. Il s’agit de réseaux de neurones \"standards\" (VGG16 et Resnet-50, ce dernier étant celui utilisé) transformés pour avoir une forme de U qui encode une image puis la décode en des prédictions par classes. Cette approche utilise des résaux pré-entraînés sur imagenet et à l'avantage d'être très simple d'utilisation. En effet, les annotations qui doivent être fournies peuvent être aussi simples que colorier avec un masque les régions d'intérêt que l'on voudrait segmenter.\n",
    "\n",
    "La prédiction de dhSegment se fait donc au pixel, c'est-à-dire que par exemple, pour une image de 640x480 pixels, le réseau va donner en sortie une \"image\" qui est en réalité une carte de probabilité de taille égale (640x480). Pour chaque pixel, la probabilité de chaque classe est calculée, ce qui nous donne donc avec 3 classes (background, section et object description) une matrice 640x480x3 avec des valeurs entre 0 et 1.\n",
    "\n",
    "L'entraînement de ce réseau se déroule de manière externe à ce notebook. Il faut suivre la procédure d'installation de dhSegment, puis créer un fichier de configuration adapté. Un exemple de fichier de configuration est donné, mais la syntaxe en susceptible de changer vu que dhSegment est un projet en cours. Tous les fichiers nécessaires à l'entraînement devraient être créés par l'étape précedente, à savoir:\n",
    "- Un dossier contenant les PNG des annotations\n",
    "- Deux fichiers csv contenant les chemins absolus vers les images de base et leurs masques correspondants\n",
    "- Un fichier classes.txt contenant le mapping de couleur vers classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tensorflow Object Detection API (TODA)\n",
    "\n",
    "La [Tensorflow Object Detection API](https://github.com/tensorflow/models/tree/master/research/object_detection) est une API développée par Tensorflow pour faciliter l'entraînement de modèles qui sont l'état de l'art dans le domaine de détection d'objets dans une image. L'utilisation principale de ces modèles est la segmentation d'images routière.\n",
    "\n",
    "Cette API offre de très nombreux réseaux pré-entraînés et préconfigurés sur le dataset [COCO](http://cocodataset.org/) et permet de rapidement tester plusieurs configurations différentes.\n",
    "\n",
    "Contrairement à dhSegment, cette approche ne prédit pas une carte de probabilité, mais donne directement des boîtes par classe. Le réseau sélectionné est une approche dite \"faster-rcnn\" avec pour base un réseau \"inception resnet v2\".\n",
    "\n",
    "L'entraînement se déroule également de manière externe au notebook. Il faut suivre la procédure d'installation [disponible ici](https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/installation.md) et créer un fichier de configuration adapté. Un exemple de fichier de configuration est donné dans ce répertoire. Tous les fichiers nécessaires à l'entraînement devraient être créés par l'étape précedente, à savoir:\n",
    "- Deux fichiers au format TFRecord contenant les annotations et les chemins absolus vers les images\n",
    "- Un fichier pbtxt contenant le mapping nombre vers classe demandé par l'API.\n",
    "\n",
    "[Voir ici](https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/running_locally.md) pour la procédure d'entraînement. Une fois l'entraînement terminé, il faut exporter le modèle pour pouvoir l'utiliser la procédure est [décrite ici](https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/exporting_models.md)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Optimisation des hyper-paramètres"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pour les deux approches, il est nécessaire de procéder à une étape de post-processing afin d'obtenir les boîtes les plus propres possible. Vu que le post-processing dépend d'hyper-paramètres arbitraire, deux modules d'optimisations ont été écrits.\n",
    "\n",
    "Le post-processing pour chaque approche est détaillé plus bas."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Post-processing dhSegment\n",
    "\n",
    "Le post processing suit les étapes suivantes:\n",
    "1. Nettoyage des probabilités avec un seuil pour chaque classe, toute probabilité plus basse se fait assigner au fond (background), deux hyper-paramètres (```bin_thresh_section``` et ```bin_thresh_content```)\n",
    "2. Dilatation des probabilités avec opencv selon un kernel paramétrable (```ksize_w``` et ```ksize_h```)\n",
    "3. Filtrage des formes plus petites qu'un threshold d'aire (```contour_area_thresh```)\n",
    "4. Ajout des lignes venant de l'OCR avec un padding (```line_padding```)\n",
    "6. Découpage des indentations, c.f. plus bas pour l'explication, (paramètres: ```indent_thresh```, ```area_thresh``` et ```crop_padding```)\n",
    "7. Complétion avec les boîtes de l'OCR\n",
    "8. Nouveau filtrage en fonction de l'aire\n",
    "9. Sélection des boîtes en prenant en compte le contenu de l'image"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Explication du découpage des indentations**\n",
    "\n",
    "Dans certaines images, les boîtes étaient tellement proches les unes des autres que la carte de probabilité montrait deux boîtes distinctes comme collée, ce qui résulte en une seule forme.\n",
    "\n",
    "<img width=\"500\" src=\"data:image/png;base64,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\" />\n",
    "\n",
    "La forme de gauche est clairement composée de deux boîtes distinctes, il faut donc créer une heuristique pour les séparer. L'idée est donc de chercher les indentations à gauche plus grandes qu'un certain seuil et de couper toute la ligne qui contient l'indentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Optimisation**\n",
    "\n",
    "Les paramètres sont ensuite optimisés sur 500 itérations à l'aide de [Scikit-optimize](https://scikit-optimize.github.io/). Une fois les paramètres obtenus, il faut ensuite les rentrer manuellement dans le code pour la prédiction des boîtes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from segmentation.optimize_boxes_dhsegment import optimize_boxes_dhsegment\n",
    "\n",
    "config['segmentation']['ocr_dir_google'] = '/path/to/google/ocr/jsons'\n",
    "config['segmentation']['model_dir'] = '/path/to/dhSegment/model'\n",
    "\n",
    "optimize_boxes_dhsegment(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Post-processing Tensorflow object detection API\n",
    "Vu que cette approche fournit directement des boîtes, les étapes de post-processing sont beaucoup plus simples et moins arbitraires.\n",
    "\n",
    "1. Filtrages des boîtes selon les seuils de probabilités fournis dans les résultats (```proba_threshold_section``` et ```proba_threshold_sale```)\n",
    "2. Complétion optionelle (paramétrable) des boîtes avec les boîtes des lignes et des lettres de l'OCR (```line_padding_section```,  ```line_padding_sale``` et quatre booléens pour chaque choix de complétion)\n",
    "3. Supression des boîtes qui sont à l'intérieur des autres\n",
    "\n",
    "L'optimisation se fait également avec Scikit-Optimize, mais uniquement sur 100 itérations, car il y a moins de paramètres à tester."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from segmentation.optimize_boxes_faster_rcnn import optimize_boxes_faster_rcnn\n",
    "\n",
    "config['segmentation']['model_dir'] = '/path/to/tensorflow/frozen/model/graph.pb'\n",
    "\n",
    "optimize_boxes_faster_rcnn(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Performance de la segmentation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "De manière visuelle, les résultats sont très similaires pour les deux approches, les boîtes semblent être souvent les mêmes, avec légèrement plus de précision pour l'approche de Tensorflow, mais quelques boîtes de plus pour dhSegment.\n",
    "\n",
    "En regardant les performances de la [métrique préconisée par COCO](http://cocodataset.org/#detection-eval) (on peut [trouver ici](https://medium.com/@jonathan_hui/map-mean-average-precision-for-object-detection-45c121a31173) une bonne explication de la métrique). On peut voir que les résultats sont en effet très similaires.\n",
    "\n",
    "|Métrique|dhSegment|TODA|\n",
    "|---|---|---|\n",
    "|mAP@ IoU=.50:.05:.95|88.26%|88.45%|\n",
    "| AP@ IoU=.75|88.41%|89.68%|\n",
    "|AP@ IoU=.5|92.43%|94.89%|\n",
    "\n",
    "Malgré la similarité de performance, le choix de ne retenir que l'approche de la TODA a été fait. En effet, l'approche dhSegment utilise beaucoup plus d'heuristiques arbitraires pour créer des boîtes, comme le découpage des indentations. Ces heuristiques n'ont aucune garantie de fonctionner à grande échelle. L'autre approche créant directement des boîtes, elle a été privilégiée."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Segmentation du dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Une fois le modèle entraîné et ces hyper-paramètres optimisés, il est possible d'inférer la segmentation pour de nouvelles images.\n",
    "\n",
    "Cette partie du code permet de sélectionner le modèle et de donner son chemin. Il faut également lui donner le chemin vers la prédiction des classes pour les images, la segmentation ne fera que sur les images de descriptions d'objets.\n",
    "\n",
    "La sortie de cette partie est un fichier numpy contenant les boîtes par image en entrée."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "from segmentation.predict_boxes import predict_boxes\n",
    "\n",
    "config['segmentation']['use_faster_rcnn'] = True or False\n",
    "config['segmentation']['model_dir'] = '/path/to/the/model/as/previous'\n",
    "config['classification']['predicted_classes_csv'] = '/path/to/the/predicted/classes.csv'\n",
    "config['segmentation']['ocr_dir_google'] = '/path/to/google/ocr/jsons'\n",
    "\n",
    "predict_boxes(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Base de données"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "L'étape suivante est de combiner l'OCR et la segmentation pour obtenir des données structurées qui peuvent être transformées en base de données."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extraction du contenu des pages"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cette étape combine donc chaque segmentation obtenue précédemment avec l'OCR.\n",
    "\n",
    "L'idée est de trouver pour chaque boîte qui correspond à un mot de l'OCR la boîte de la segmentation qui lui correspond (ou aucune). Ceci est simplement fait en trouvant le plus grand chevauchement entre une boîte de l'OCR et celle de la segmentation.\n",
    "\n",
    "Une fois les boîtes trouvées nous obtenons une liste d'entités étant soit des sections soit des objets avec les coordonées et le texte leur correspondant.\n",
    "\n",
    "**Numéros de références**\n",
    "\n",
    "Vu que les numéros de références sont une des portes d'entrées des objets et qu'ils sont très utiles pour quantifier le nombre d'erreur, une correction en post-processing, selon un algorithme relativement simple qui complète automatiquement les numéros, si l'espace le permet, entre deux séquences considérées comme valides. Les séquences sont considérées comme valides si elles sont composées de quatre chiffres croissants plus grand que les séquences précédentes.\n",
    "\n",
    "**Sections**\n",
    "\n",
    "Vu l'impossibilité de séparer les deux types de sections qui existent, à savoir les auteurs et les catégories, uniquement avec la segmentation, ces sections ont été triées manuellement dans les deux catégories. Il faut donc fournir un fichier csv contenant les sections normalisées (strip, minuscules et sans charactères spéciaux) et leures classes (author, category).\n",
    "\n",
    "Cette classification, ainsi que la taille en pixel des lettres de certaines sections sont ensuite utilisées pour créer une hiérarchie des sections (Par exemple \"Tableau\" est en desssus de \"Degas\"). Cette hiérarchie est ensuite utilisée pour créer la base de données. Après observation des données, un choix arbitraire a été pris de s'arrêter à une profondeur de deux dans la hiérarchie, on a donc ainsi des catégories qui peuvent contenir soit des catégories ou des auteurs, mais pas de sous niveau.\n",
    "\n",
    "**Fichiers de sortie**\n",
    "\n",
    "Cette étape créee deux fichiers binaires python.\n",
    "\n",
    "Un fichier contenant une dataframe pandas avec le contenu des pages. Cette dataframe peut être réutilisée afin de compléter le fichier csv des sections.\n",
    "\n",
    "Un autre fichier contenant un arbre de la hiérachie des sections sous la forme du module anytree."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [],
   "source": [
    "from database.extract_page_content import extract_page_content\n",
    "\n",
    "config['database']['ocr_dir'] = '/path/to/google/ocr/jsons'\n",
    "config['database']['section_classified_csv_path'] = '/path/to/section_classified.csv'\n",
    "\n",
    "extract_page_content(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Prépartion des données pour sql"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cette étape prend les données extraites dans l'étape précédente et génére des fichiers csv pour chaque table de la base de données finale.\n",
    "\n",
    "Cette étape prend également en entrée une liste des divers acteurs extraits des métadonnées. Il est possible de compléter le fichier excels s'il y a de nouveaux acteurs. À noter que les données ne proviennent pas de segmenation, mais des métadonnées disponibles sur la bibliothèque numérique de l'INHA.\n",
    "\n",
    "Une description plus précise de la base de données est disponible [ici](https://github.com/sriak/aucase-inha/blob/master/description_schema_sql.md)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [],
   "source": [
    "from database.prepare_data_for_sql import prepare_data_for_sql\n",
    "\n",
    "config['database']['actor_excel_path'] = '/path/to/actor.xslx'\n",
    "\n",
    "prepare_data_for_sql(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "scrolled": true
   },
   "source": [
    "### Importation des données dans une base mysql"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Une fois les csv de chaque table créés, le plus simple est de les importer via python. En effet, vu que certains des textes sont multilignes et que le csv n'est pas un format très bien défini, il est parfois dificile de directement l'importer via mysql.\n",
    "\n",
    "Ce code prend les informations de connection à la base mysql et importe les différents fichiers csv dans la base de données."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from database.import_into_mysql import import_into_mysql\n",
    "\n",
    "config['database']['mysql_host'] = 'localhost'\n",
    "config['database']['mysql_schema'] = 'aucase'\n",
    "config['database']['mysql_user'] = 'user'\n",
    "config['database']['mysql_pass'] = 'password'\n",
    "\n",
    "import_into_mysql(config)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.6"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": false,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": true,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}