{
    "info": {
        "author": "Oslandia",
        "author_email": "info@oslandia.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Intended Audience :: Developers",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: Implementation :: CPython",
            "Topic :: Scientific/Engineering :: Artificial Intelligence"
        ],
        "description": "\nIn this project we use a set of images provided\nby [Mapillary](https://www.mapillary.com/), in order to investigate on the\npresence of some typical street-scene objects (vehicles, roads,\npedestrians...). Mapillary released this dataset on July 2017, it\nis [available on its website](https://www.mapillary.com/dataset/vistas)\nand may be downloaded freely for a research purpose.\n\nAs inputs, Mapillary provides a bunch of street scene images of various sizes\nin a `images` repository, and the same images after filtering process in\n`instances` and `labels` repositories. The latter is crucial, as the filtered\nimages are actually composed of pixels in a reduced set of colors. Actually,\nthere is one color per object types; and 66 object types in total.\n\n![Example of image, with its filtered version](./images/MVD_M2kh294N9c72sICO990Uew.png)\n\nThere are 18000 images in the training set, 2000 images in the validation set,\nand 5000 images in the testing set. The testing set is proposed only for a\nmodel test purpose, it does not contain filtered versions of images.\n\nTo complete the project, and make the test easier, a randomly-generated shape model is also\navailable. In this dataset, some simple coloured geometric shapes are inserted into each picture,\non a total random mode. There can be one rectangle, one circle and/or one triangle per image, or\nneither of them. Their location into each image is randomly generated (they just can't be too close\nto image borders). The shape and background colors are randomly generated as well.\n\nThe picture below shows an example of image generated in this way:\n\n![Example of shape image](./images/shape_00000.png)\n\n# Content\n\nThe project contains some Python materials designed to illustrate the Tensorflow and Keras\nlibraries (snippets and notebooks)\n\n+ [article](./article) contains the original text of articles that have been published\n  on [Oslandia blog](http://oslandia.com/en/blog/) on this topic\n+ [deeposlandia](./deeposlandia) contains main Python modules to train and test convolutional\n  neural networks\n+ [images](./images) contains some example images to illustrate the Mapillary dataset as well as\n  some preprocessing analysis results\n+ [notebooks](./notebooks) contains some Jupyter notebooks that aim at describing data or basic\n  neural network construction\n+ [tests](./tests) contains some test modules to guarantee the functioning of a bunch of snippets;\n  it uses the `pytest` framework.\n\nAdditionally, running the code may generate extra subdirectories in the data repository.\n\n# Installation\n\n## Requirements\n\nThis project needs to load the following Python dependencies:\n\n+ cv2\n+ keras\n+ h5py\n+ logging\n+ matplotlib\n+ numpy\n+ pandas\n+ PIL\n+ tensorflow\n\nAs a remark, the code has been run with Python3 (version 3.5). These dependencies are recalled in\n`setup.py` file, and additional dependencies for developing purpose are listed in\n`requirements-dev.txt`.\n\n## From source\n\n```\n$ git clone https://github.com/Oslandia/deeposlandia\n$ cd deeposlandia\n$ virtualenv -p /usr/bin/python3 venv\n$ source venv/bin/activate\n(venv)$ pip install -r requirements-dev.txt\n```\n\n# Running the code\n\nThis project supposes that you have downloaded the Mapillary image dataset.\n\n## Data preprocessing\n\nFirst of all, preprocessed versions of raw Mapillary dataset has to be generated before any neural\nnetwork training:\n\n```\npython deeposlandia/datagen.py -D mapillary -s 224 -a -p ./any-data-path -t 18000 -v 2000 -T 5000\n```\n\nThe previous command will generates a set of 224 * 224 images based on Mapillary dataset. The raw\ndataset must be in `./any-data-path/input`. If the `-a` argument is specified, the preprocessed\ndataset will be stored in `./any-data-path/preprocessed/224_aggregated`, otherwise it will be\nstored in `./any-data-path/preprocessed/224_full`. The aggregation is applied on dataset labels,\nthat can be grouped in Mapillary case (and only in Mapillary case) to reduce their number from 65\nto 11.\n\nAdditionally, the preprocessed dataset may contain less images than the raw dataset: the `-t`, `-v`\nand `-T` arguments refer respectively to training, validation and testing image quantities. The\namount indicated as an example correspond to raw dataset size.\n\nIn the Shapes datase case, this preprocessing step generates a bunch of images from scratch.\n\nAs an easter-egg feature, label popularity is also printed by this command (proportion of images\nwhere each label appears in the preprocessed dataset).\n\n## Model training\n\nThen the model training itself may be undertaken:\n\n```\npython deeposlandia/train.py -M feature_detection -D mapillary -s 512 -e 5\n```\n\nIn this example, 512 * 512 Mapillary images will be exploited from training a feature detection\nmodel. Here the training will take place for five epoches. An inference step is always undertaken\nat the end of the training.\n\nHere comes the parameter handled by this program:\n+ `-a`: aggregate labels (*e.g.* `car`, `truck` or `caravan`... into a `vehicle` labels); do\n  nothing if applied to `shapes` dataset.\n+ `-b`: indicate the batch size (number of images per training batch, 50 by default).\n+ `-D`: dataset (either `mapillary` or `shapes`).\n+ `-d`: percentage of dropped out neurons during training process. Default value=1.0, no dropout.\n+ `-e`: number of epochs (one epoch refers to the scan of every training image). Default value=0,\n  the model is not trained, inference is done starting from the last trained model.\n+ `-h`: show the help message.\n+ `-ii`: number of testing images (default to 5000, according to the Mapillary dataset).\n+ `-it`: number of training images (default to 18000, according to the Mapillary dataset).\n+ `-iv`: number of validation images (default to 2000, according to the Mapillary dataset).\n+ `L`: starting learning rate. Default to 0.001.\n+ `l`: learning rate decay (according to\n  the [Adam optimizer definition](https://keras.io/optimizers/#adam)). Default to 1e-4.\n+ `-M`: considered research problem, either `feature_detection` (determining if some labelled\n  objects are on an image) or `semantic_segmentation` (classifying each pixel of an image).\n+ `-N`: neural network architecture, either `simple` (default value), or `vgg16` for the feature\n  detection problem, `simple` is the only handled architecture for semantic segmentation.\n+ `-n`: neural network name, used for checkpoint path naming. Default to `cnn`.\n+ `-p`: path to datasets, on the file system. Default to `./data`.\n+ `-s`: image size, in pixels (height = width). Default to 256.\n\n## Model testing\n\nTrained models may be tested after the training process. Once a model is trained, a checkpoint\nstructure is recorded in `<datapath>/<dataset>/output/<problem>/checkpoints/<instance-name>`. It is\nthe key point for inference.\n\nThe model testing is done as follows:\n\n```\npython deeposlandia/inference.py -D shapes -i ./data/shapes/preprocessed/64_full/testing/images/shape_00000.png\n```\n\nIn this example, a label prediction will be done on a single image, for `shapes` dataset in the\nfeature detection case. The trained model will be recovered by default in\n`<datapath>/<dataset>/output/<problem>/checkpoints/`, by supposing that an optimized model (*e.g.*\nregarding hyperparameters) has been produced. If the hyperparameters are specified (training batch\nsize, dropout rate, starting learning rate, learning rate decay, model architecture and even model\nname), knowing that the image size is given by the first tested image, the trained model is\nrecovered in `<datapath>/<dataset>/output/<problem>/checkpoints/<instance>/`, where `<instance>` is\ndefined as:\n\n```\n<model_name>-<image_size>-<network_architecture>-<batch_size>-<aggregation_mode>-<dropout>-<start_lr>-<lr_decay>\n```\n\nIf no trained model can be found in the computed path, the label prediction is done from scratch\n(and will be rather inaccurate...).\n\nThe list of handled parameters is as follows:\n+ `-a`: aggregate labels. Used to point out the accurate configuration file, so as to get the\n  number of labels in the dataset.\n+ `-b`: training image batch size. Default to `None` (aims at identifying trained model).\n+ `-D`: dataset (either `mapillary` or `shapes`)\n+ `-d`: percentage of dropped out neurons during training process. Default to `None` (aims at\n  identifying trained model).\n+ `-i`: path to tested images, may handle regex for multi-image selection.\n+ `L`: starting learning rate. Default to `None` (aims at identifying trained model).\n+ `l`: learning rate decay (according to\n  the [Adam optimizer definition](https://keras.io/optimizers/#adam)). Default to `None` (aims at\n  identifying trained model).\n+ `-M`: considered research problem, either `feature_detection` (determining if some labelled\n  objects are on an image) or `semantic_segmentation` (classifying each pixel of an image).\n+ `-N`: trained model neural network architecture. Default to `None` (aims at identifying trained\n  model).\n+ `-n`: neural network name. Default to `None` (aims at identifying trained model).\n+ `-p`: path to datasets, on the file system. Default to `./data`.\n\n# License\n\nThe program license is described in [LICENSE.md](./LICENSE.md).\n\n___\n\nOslandia, April 2018\n\n\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/Oslandia/deeposlandia",
        "keywords": "deep learning,convolutional neural networks,image,Keras",
        "license": "MIT",
        "maintainer": "Oslandia",
        "maintainer_email": "",
        "name": "deeposlandia",
        "package_url": "https://pypi.org/project/deeposlandia/",
        "platform": "",
        "project_url": "https://pypi.org/project/deeposlandia/",
        "project_urls": {
            "Homepage": "https://github.com/Oslandia/deeposlandia"
        },
        "release_url": "https://pypi.org/project/deeposlandia/0.4/",
        "requires_dist": [
            "opencv-python (<=3.4.0.12)",
            "numpy (<=1.14.2)",
            "pandas (<=0.22.0)",
            "pillow (<=5.0.0)",
            "tensorflow (<=1.6)",
            "keras (<=2.1.5)",
            "matplotlib (<=2.2.0)",
            "h5py (<=2.7.1)"
        ],
        "requires_python": ">=3",
        "summary": "Automatic detection and semantic image segmentation with deep learning",
        "version": "0.4"
    },
    "last_serial": 3831573,
    "releases": {
        "0.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5afb878d7a24b105af8bb2ff3d705c33",
                    "sha256": "5868af000702e640d85fa4689a105130838c5d5d03446899147e6df2091fc076"
                },
                "downloads": -1,
                "filename": "deeposlandia-0.4-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "5afb878d7a24b105af8bb2ff3d705c33",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3",
                "size": 34431,
                "upload_time": "2018-05-03T16:26:30",
                "url": "https://files.pythonhosted.org/packages/a1/06/ffb2331853fee4f106ee34c0f0745a5e8eff5f8d9dc9a726de14b558d33f/deeposlandia-0.4-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "0ef16adb6c5b18d84be24a0a4adf416b",
                    "sha256": "f66af13b713149da2d8d1b74f687b78380df65c407127ae5033ea4a677ed6c21"
                },
                "downloads": -1,
                "filename": "deeposlandia-0.4.tar.gz",
                "has_sig": false,
                "md5_digest": "0ef16adb6c5b18d84be24a0a4adf416b",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3",
                "size": 24269,
                "upload_time": "2018-05-03T16:26:31",
                "url": "https://files.pythonhosted.org/packages/c7/ca/a02cc70bac6f00fb2fbcb7f7ae8f0ef45a8487a7ca6796989ae4d35f1975/deeposlandia-0.4.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "5afb878d7a24b105af8bb2ff3d705c33",
                "sha256": "5868af000702e640d85fa4689a105130838c5d5d03446899147e6df2091fc076"
            },
            "downloads": -1,
            "filename": "deeposlandia-0.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5afb878d7a24b105af8bb2ff3d705c33",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3",
            "size": 34431,
            "upload_time": "2018-05-03T16:26:30",
            "url": "https://files.pythonhosted.org/packages/a1/06/ffb2331853fee4f106ee34c0f0745a5e8eff5f8d9dc9a726de14b558d33f/deeposlandia-0.4-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "0ef16adb6c5b18d84be24a0a4adf416b",
                "sha256": "f66af13b713149da2d8d1b74f687b78380df65c407127ae5033ea4a677ed6c21"
            },
            "downloads": -1,
            "filename": "deeposlandia-0.4.tar.gz",
            "has_sig": false,
            "md5_digest": "0ef16adb6c5b18d84be24a0a4adf416b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3",
            "size": 24269,
            "upload_time": "2018-05-03T16:26:31",
            "url": "https://files.pythonhosted.org/packages/c7/ca/a02cc70bac6f00fb2fbcb7f7ae8f0ef45a8487a7ca6796989ae4d35f1975/deeposlandia-0.4.tar.gz"
        }
    ]
}