Release v2.2 pushed

Author: Loïc Vanden Bemden

HOWTO.md

@@ -1,6 +1,39 @@
 # Blob Simulation & Detection
 Détection d'un blob dans une image ainsi que détection des comprimés de nourriture. Simulation d'un blob dans PyGame à travers un système multi-agents à connaissance partagée.
 
+1. [How to use](HOWTO.md)
+2. [Requirements](#requirements)
+3. [Pour aller plus loin](TOGOFURTHER.md)
+4. [Releases](#releases)
+5. [License](#license)
+6. [Mentions légales](#mentions-legales)
+
+## How to use
+Vous trouverez la description détaille des différents scripts et des fichiers de configuration [ici](HOWTO.md).
+
+## Requirements
++ [Python 3.6.8](https://www.python.org/downloads/release/python-368/) - [Documentation](https://docs.python.org/3.6/)
++ [Numpy 1.16.4](https://pypi.org/project/numpy/1.16.4/) - BSD License
++ [Pathfinding 0.0.4](https://pypi.org/project/pathfinding/0.0.4/) - MIT License
++ [PyGame 1.9.6](https://pypi.org/project/pygame/1.9.6/) - LGPL License - [Documentation](https://www.pygame.org/docs/)
++ [Imutils 0.5.2](https://pypi.org/project/imutils/0.5.2/) - MIT License
++ [OpenCV Python 4.1.0.25](https://pypi.org/project/opencv-python/4.1.0.25/) - MIT License - [Documentation](https://docs.opencv.org/4.1.0/)
+
+## Pour aller plus loin
+Vous trouverez quelques articles scientifiques et conseils de lecture en lien avec le développement de ce projet [ici](TOGOFURTHER.md).
+
+## Releases
+## Release 2.2 - *24/06/2019*
+### Modifications : 
++ Ajout d'un fichier requirements.txt avec les versions des modules utilisées
++ Transformation de l'argument "input" en argument positionnel
+
+### Scripts : 
++ Setup : `python setup.py data/example.jpg`
++ Detection : `python detect.py data/example.jpg`
++ Simulation : `python play.py data/output-examples/example-detect.board -s 3`
++ Compare : `python compare.py data/output-examples/simulation/10_loops/10_loops.board data/output-examples/simulation/100_loops/100_loops.board -s 3`
+
 ## Release 2.1 - *7/06/2019*
 
 ### Modifications : 

README.md

@@ -0,0 +1,73 @@
+# Pour aller plus loin
+## Physarum polycephalum ou Blob
+Beaucoup d'articles scientifiques (et des livres de vulgarisation) existent sur le blob mais ceux-ci se concentrent sur l'analyse de son comportement et sur sa faculté à résoudre certains problèmes. La plupart de ses problèmes sont liés à des représentations sous forme de graphe (TSP Problem, Dijkstra, Voronoï diagram, Delaunay triangluation, ...) Il n'y a donc pas d'articles cherchant à modéliser son comportement. Au niveau détection, il existe le code MatLab fourni par le CNRS.
+
+**Dussutour**, Audrey (2017).*Tout ce que vous avez toujours voulu savoir sur le blob sans avoir jamais oser le demander.* Des Équateurs, Hors collection, 179 pages.
+
+**Tsuda**, Soichiro, **Zauner**, Klaus-Peter and **Gunji**, Yukio-Pegio (2006) *Robot Control: From Silicon Circuitry to Cells.*      Ijspeert, Auke Jan, Masuzawa, Toshimitsu and Kusumoto, Shinji (eds.)      In Biologically Inspired Approaches to Advanced Information Technology, Second International Workshop, BioADIT 2006, Osaka, Japan, January 26-27, 2006, Proceedings.   Springer.  pp. 20-32.
+
+**Whiting** JG, **Jones** J, **Bull** L, **Levin** M, **Adamatzky** A.* Towards a Physarum learning chip*. *Sci Rep*. 2016;6:19948. Published 2016 Feb 3.
+
+**Jones, Jeff, &amp; Andrew Adamatzky.** [Computation of the travelling salesman problem by a shrinking blob](http://www.phychip.eu/wp-content/uploads/2013/03/Computation-of-the-travelling-salesman-problem-by-a-shrinking-blob.pdf) *Natural Computing,* (13), 1, p. 1-16, (2014).</p>
+**Shirakawa**, Tomohiro &amp; **Adamatzky**, Andrew &amp; **Gunji**, Yukio-Pegio &amp; **Miyake**, Yoshihiro. (2009). On Simultaneous Construction of Voronoi Diagram and Delaunay Triangulation by. I. J. Bifurcation and Chaos. 19. 3109-3117. 10.1142/S0218127409024682.
+
+## Système multi-agents
+
+En soi, le blob n'est pas un système multi-agents puisqu'il n'est constitué que d'une seule cellule. Néanmoins, la plupart des problèmes qu'il arrive à résoudre sont aujourd'hui plus facilement résolu par des systèmes multi-agents.
+
+Un type connu de système multi-agents est le comportement d'une colonie de fourmis. On retrouve donc le lien entre blob et fourmis à travers ses différents problèmes. Audrey Dussutour, avant de se concentrer sur le blob, se spécifiait dans le comportement des fourmis également.
+
+NetLogo est un langage de programmation pour système multi-agents, basé sur du Logo (lui-même basé sur du LISP). L'environnement n'est pas ultra-modulable mais il fournit une série de modèles implémentés et prêts à l'emploi. Certains de ceux-ci (listés ci-dessous) correspondent aux problèmes résolus par le blob ou par des algorithmes ACO (Ants Colony Optimization).
+
+Il existe également un pseudo-code permettant de simuler le comportement d'un blob à travers une approche multi-agents.
+
+Wilensky, U. (1999). **NetLogo**. [http://ccl.northwestern.edu/netlogo/](http://ccl.northwestern.edu/netlogo/) Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.</p>
+
+### Modèles
++ Stonedahl, F. and Wilensky, U. (2008).  [**NetLogo Virus on a Network model**](http://ccl.northwestern.edu/netlogo/models/VirusonaNetwork). Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.
+
++ Wilensky, U. (2005).  [**NetLogo Preferential Attachment model**](http://ccl.northwestern.edu/netlogo/models/PreferentialAttachment). Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.
+
++ Stonedahl, F. and Wilensky, U. (2008). [**NetLogo Diffusion on a Directed Network model**](http://ccl.northwestern.edu/netlogo/models/DiffusiononaDirectedNetwork).  Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.
+
++ Grider, R. and Wilensky, U. (2015). [**NetLogo Paths model**](http://ccl.northwestern.edu/netlogo/models/Paths).  Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL
++ Wilensky, U. (1997).  [**NetLogo Ant Lines model**](http://ccl.northwestern.edu/netlogo/models/AntLines).  Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.
+
+[Pseudo-code multi-agents pour simuler un blob](http://www.simulace.info/index.php/Multi-agent_systems) dans NetLogo.
+
+## IA &amp; Optimization Algorithm Problems
+Aucune base de données n'étant disponible pour simuler le blob dans le cas précis du projet, il est nécessaire d'en revenir à des comportements prédits de manière algorithmiques.
+
+Les techniques classiques d'IA utilisées pour résoudre des problèmes par exploration d'arbres de solution sont donc à privilégier. Le blob peut être envisagé comme un joueur devant découvrir au plus vite des ressources dans un environnement inconnu et à optimiser les connexions entre ces ressources. Sur ce second point, il travaille donc comme un algorithme ACO. Pour la partie découverte, il existe également déjà des simulateurs de parcours de fourmis mais ceux trouvés sont difficilement modifiables.
+
+**Russel**, Stuart Jonathan, **Norvig**, Peter (2009). *Artificial Intelligence : A modern approach*. Pearson, 3rd Edition,&nbsp; 1152 pages.
+
+**geoyar**(2013). [*Applying Ant Colony Optimization Algorithms to Solve the Traveling Salesman Problem*](https://www.codeproject.com/articles/644067/applying-ant-colony-optimization-algorithms-to-sol). Code Project.
+
+**Kohout** Peter (2006). [*Genetic and Ant Colony Optimization Algorithms*](https://www.codeproject.com/Articles/5436/Genetic-and-Ant-Colony-Optimization-Algorithms). Code Project.
+
+**Lichtenberg** Malte, **Tittmann** Lucas (2012). [Programmation Project - Ant Simulation](https://github.com/Andarin/Ant-Colony-Simulation-Python). Andarin, Github Code (Python 2, Cython).
+
+**Akavall** (2019). [Ant Colony Optimization Algorithm using Python](https://github.com/Akavall/AntColonyOptimization). Akavall, Github Code (Python 3).
+
+## License
+Copyright (C) 2019 - UMons
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+## Mentions légales
+Cette publication a été réalisée dans le cadre du projet Interreg de coopération transfrontalière C2L3PLAY, cofinancé par L’Union Européenne. Avec le soutien du Fonds européen de développement régional / Met steun van het Europees Fonds voor Regionale Ontwikkeling
+
+<img src="https://crossborderlivinglabs.eu/wp-content/uploads/2018/02/LogoProjets_GoToS3_C2L3PLAY.png" width="200px"/>

TOGOFURTHER.md

@@ -21,19 +21,19 @@
 
 
 def main():
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--first", required=True, help="first board file")
-    ap.add_argument("--second", required=True, help="second board file")
+    ap = argparse.ArgumentParser(description="Compare two board files and express it as an image.")
+    ap.add_argument("input_1", metavar= "FIRST_INPUT", help="first board file")
+    ap.add_argument("input_2", metavar= "SECOND_INPUT", help="second board file to compare with")
     ap.add_argument("-s", "--scale", type=float, default=10,
                     help="Scales board resolution by this factor (default: x10)")
     ap.add_argument("-o", "--output", type=str, help="Give a name to save the jpeg file")
     args = ap.parse_args()
 
     board_1 = board.Board(0, 0)
-    board_1.load(args.first)
+    board_1.load(args.input_1)
 
     board_2 = board.Board(0, 0)
-    board_2.load(args.second)
+    board_2.load(args.input_2)
 
     board_comp = board_1.compare(board_2)
 

compare.py

@@ -22,8 +22,8 @@
 
 
 def main():
-    ap = argparse.ArgumentParser()
-    ap.add_argument("-i", "--input", required=True, help="Uses this input as image for detection")
+    ap = argparse.ArgumentParser("Detect a blob and foods in an image.")
+    ap.add_argument("input", metavar="INPUT", help="Uses this input as image for detection")
     ap.add_argument("-s", "--scale", type=float, default=0.10, help="Scales images by this factor (default: x0.1)")
     ap.add_argument("-c", "--config", type=str, default="detection/config.json",
                     help="Loads config from this file (default: detection/config.json)")
@@ -57,7 +57,9 @@ def main():
     else:
         file_path = None
 
-    print_results(orig, blob_mask, blob, food_mask, food_img, dsc_img, args.scale, file_path, args.hide)
+    labels = ["Original", "Discrete", "Blob Mask", "Blob", "Food Mask", "Food Regions"]
+    images = [orig, img, blob_mask, blob, food_mask, food_img]
+    print_results(labels, images, args.scale, file_path, args.hide, nbr_width=2)
 
 
 if __name__ == "__main__":

detect.py

@@ -15,10 +15,21 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 from detection.utils import *
+from math import ceil
 
 
 def detect(input_file, config):
-
+    """
+    Starts blob detection in the image and returns
+    - the part of the image used (resized and warp perpective)
+    - blob mask detected
+    - blob segmented image
+    - food mask detected
+    - the image with food regions
+
+    :param input_file: string filename for jpeg image detection
+    :param config: dict with config used for detection
+    """
     img = cv2.imread(input_file)
     height, width, _ = img.shape
 
@@ -64,56 +75,62 @@ def detect(input_file, config):
     return img, blob_mask, blob, food_mask, food_img
 
 
-def print_results(orig, blob_mask, blob, food_mask, food, discrete, scale=1.0, filename=None, hide=False):
+def print_results(labels, images, scale=1.0, filename=None, hide=False, nbr_width=2):
+    """
+    Aggregate and show images in one window with each label displayed at the top of them.
+    It can as well save the aggregated image.
+    Each line contains 'nbr_width' images.
+    If the number of images doesn't fit the last line, it's padded with a zero image.
+
+    :param labels: each label to use for each image in images. assert len(labels) == len(images)
+    :param images: each image to print in results window
+    :param scale: the scale to use for results window with respect to image size
+    :param filename: if provide, save results window under 'filename'.jpg name
+    :param hide: if true, the results window isn't shown
+    :param nbr_width: number of images to fit in line
+    """
     padding = 35
-    nbr_width = 2
-    nbr_height = 3
     font = cv2.FONT_HERSHEY_SIMPLEX
     fontsize = 0.45
     thickness = 1
 
-    scaled_height = int(orig.shape[0]*scale)
-    scaled_width = int(orig.shape[1]*scale)
+    scaled_height = int(images[0].shape[0]*scale)
+    scaled_width = int(images[0].shape[1]*scale)
+    pad = np.zeros((scaled_height, padding, 3), dtype=np.uint8)
+    line_pad = np.zeros((padding, (scaled_width + padding) * nbr_width + padding, 3), dtype=np.uint8)
+    img_pad = np.zeros((scaled_height, scaled_width, 3), dtype=np.uint8)
+
+    print_images = []
+    for image in images:
+        full_color = image if len(image.shape) == 3 else cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+        print_image = cv2.resize(full_color, (scaled_width, scaled_height))
+        print_images.append(print_image)
+
+    middle = ((0, int(scaled_height / 2)), (scaled_width, int(scaled_height / 2)))
+    cv2.line(print_images[0], middle[0], middle[1], (0, 255, 0), thickness=1)
+    cv2.putText(print_images[0], 'Mid Line', (middle[0][0] + 5, middle[0][1] - 5),
+                font, fontsize, (0, 255, 0), thickness, cv2.LINE_AA)
+
+    lines = [line_pad]
+    for j in range(ceil(len(images)/nbr_width)):
+        concat_line = [pad]
+        for i in range(nbr_width):
+            if i + j * nbr_width < len(images):
+                concat_line.append(print_images[i + j * nbr_width])
+            else:
+                concat_line.append(img_pad)
+            concat_line.append(pad)
 
-    pad = np.zeros((scaled_height, padding, orig.shape[2]), dtype=np.uint8)
-    line_pad = np.zeros((padding, (scaled_width + padding) * nbr_width + padding, orig.shape[2]), dtype=np.uint8)
-    print_img = cv2.resize(orig, (scaled_width, scaled_height))
+        lines.append(np.concatenate(tuple(concat_line), axis=1))
+        lines.append(line_pad)
 
-    middle = ((0, int(scaled_height/2)), (scaled_width, int(scaled_height/2)))
-    cv2.line(print_img, middle[0], middle[1], (0, 255, 0), thickness=1)
-    cv2.putText(print_img, 'Mid Line', (middle[0][0] + 5, middle[0][1] - 5),
-                font, fontsize, (0, 255, 0), thickness, cv2.LINE_AA)
+    aggregate = np.concatenate(tuple(lines))
 
-    print_blob_mask = cv2.resize(cv2.cvtColor(blob_mask, cv2.COLOR_GRAY2BGR), (scaled_width, scaled_height))
-    print_blob = cv2.resize(blob, (scaled_width, scaled_height))
-    print_food_mask = cv2.resize(cv2.cvtColor(food_mask, cv2.COLOR_GRAY2BGR), (scaled_width, scaled_height))
-    print_food = cv2.resize(food, (scaled_width, scaled_height))
-    print_discrete = cv2.resize(discrete, (scaled_width, scaled_height))
-
-    concat_line1 = np.concatenate((pad, print_img, pad, print_discrete, pad), axis=1)
-    concat_line2 = np.concatenate((pad, print_blob_mask, pad, print_blob, pad), axis=1)
-    concat_line3 = np.concatenate((pad, print_food_mask, pad, print_food, pad), axis=1)
-
-    aggregate = np.concatenate((line_pad, concat_line1, line_pad, concat_line2, line_pad, concat_line3, line_pad))
-
-    cv2.putText(aggregate, 'Original:',
-                (0 * (scaled_width + padding) + padding + 5, 0 * (scaled_height + padding) + padding - 5),
-                font, fontsize, (255, 255, 255), thickness, cv2.LINE_AA)
-    cv2.putText(aggregate, 'Discrete:',
-                (1 * (scaled_width + padding) + padding + 5, 0 * (scaled_height + padding) + padding - 5),
-                font, fontsize, (255, 255, 255), thickness, cv2.LINE_AA)
-    cv2.putText(aggregate, 'Blob Mask:',
-                (0 * (scaled_width + padding) + padding + 5, 1 * (scaled_height + padding) + padding - 5),
-                font, fontsize, (255, 255, 255), thickness, cv2.LINE_AA)
-    cv2.putText(aggregate, 'Blob:',
-                (1 * (scaled_width + padding) + padding + 5, 1 * (scaled_height + padding) + padding - 5),
-                font, fontsize, (255, 255, 255), thickness, cv2.LINE_AA)
-    cv2.putText(aggregate, 'Food Mask:',
-                (0 * (scaled_width + padding) + padding + 5, 2 * (scaled_height + padding) + padding - 5),
-                font, fontsize, (255, 255, 255), thickness, cv2.LINE_AA)
-    cv2.putText(aggregate, 'Food Regions:',
-                (1 * (scaled_width + padding) + padding + 5, 2 * (scaled_height + padding) + padding - 5),
-                font, fontsize, (255, 255, 255), thickness, cv2.LINE_AA)
+    for i in range(len(print_images)):
+        cv2.putText(aggregate, labels[i],
+                    ((i % nbr_width) * (scaled_width + padding) + padding + 5,
+                     int(i/nbr_width) * (scaled_height + padding) + padding - 5),
+                    font, fontsize, (255, 255, 255), thickness, cv2.LINE_AA)
 
     if filename is not None:
         cv2.imwrite(filename + ".jpg", aggregate)
@@ -125,6 +142,15 @@ def print_results(orig, blob_mask, blob, food_mask, food, discrete, scale=1.0, f
 
 
 def discretize(blob_img, food_mask, width, height):
+    """
+    Transform blob and foods into a numeric blob and foods with discrete 'width' and 'height' resolution
+
+    :param blob_img: a blob segmented numpy image
+    :param food_mask: a food mask numpy image
+    :param width: (int) the discrete width resolution
+    :param height: (int) the discrete height resolution
+    :return: the new image (as a saved simulated-like), the blob values in the image and the complete food position list
+    """
     img_height, img_width, _ = blob_img.shape
 
     discrete_blob = cv2.resize(blob_img, (width, height), interpolation=cv2.INTER_NEAREST)