{
    "info": {
        "author": "Alexina Coullandreau",
        "author_email": "",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.7",
            "Topic :: Multimedia :: Graphics",
            "Topic :: Multimedia :: Graphics :: Viewers",
            "Topic :: Scientific/Engineering :: Visualization"
        ],
        "description": "geo_rendering package - documentation\n=========================================\n\n\nPurpose of this package\n-----------------------\n\nThis package is designed to render maps from a **shapefile**.\nIt allows you to:\n\n- create an image file of any size with the shapefile map rendered on it\n- convert the projection system to scale the shapefile map on the image_size\n- draw points and fill shapes on the map\n- add text on the map\n\n\nRequirements\n------------\n\nThe code is written in Python 3.7.\n\nThere are several dependencies for this package. The versions provided here are those used for testing.\n\n- numpy 1.16.4\n- opencv-python 4.1.0\n- pandas 0.25.0\n- pyshp 2.1.0\n- unittest (python standard library)\n- mock 3.0.5 (or unittest.mock)\n\n\nInstallation\n------------\n\nTo install the package:\n\n```\npip install geo-rendering\n```\n\nIt relies in particular on two libraries: OpenCV and pyshp.\nThe setup.py file lists all dependencies.\n\nTutorial\n---------\n\nA brief introduction on how to use this package is available on [Medium](https://medium.com/@mozart38).\n\n\nCode documentation\n------------------\n\nPackage functions\n-----------------\n\n**ContextualText** is the class responsible for text rendering. \nAn instance is created provided three arguments: \n```\ngeo_rendering.ContextualText(content, position, color)\n```\n\nThese arguments are used to instantiate properties of the instance:\n- .content: the text to display\n- .position: the coordinates (in pixels) of the bottom left point of the text - \n- .color: as a tuple of BGR color\n\nOther properties are set by default but can be edited at any time:\n- .font (default cv2.FONT_HERSHEY_SIMPLEX)\n- .font_style (default cv2.LINE_AA)\n- .text_size (default 1)\n- .thickness (default 1)\n\nOnly one method is available: \n- display_text(map_to_edit), that renders the text on the map file provided as an argument\n\nSee [OpenCV ](https://docs.opencv.org/3.0-beta/modules/imgproc/doc/drawing_functions.html) requirements for cv2.putText for more details. \n\n-----------------\n\n**Map** is the class responsible for the rendering of a map provided a shapefile. \n\nAn instance is created provided three arguments:\n```\ngeo_rendering.Map(shapefile, image_size, [background_color])\n```\n\nThese arguments are used to instantiate properties of the instance:\n- .shapefile: a Shapefile class instance\n- .image_size: the image size (width, height) in pixels\n- .background_color[optional]: the color of the background image (default black)\n\nOther properties are set by default but can be edited at any time:\n- .shape_dict: a dictionary of all shapes in the shapefile (key is the index of the shape, value a instance of the Shape class)\n- .shape_dict_filt: equivalent to the shape_dict unless part of the shapefile is to be rendered (filter)\n- .max_bound / .min_bound: the extreme coordinates of the boundaries of the shapefile\n- .projection (default {})\n- .map_file: the image file\n\nThree methods are available: \n- build_shape_dict(ref_df): constructs the dictionary using the id of each shape from the shapefile and instantiating instances of the Shape class for each of them ; it uses the dataframe extracted from the shapefile (see below)\n- find_max_coords(): computes the max_bound / min_bound\n- render_map(): generates an image file with a size of image_size and plots each shape of the shape_dict_filt\n\nSee [OpenCV ](https://docs.opencv.org/3.0-beta/modules/imgproc/doc/drawing_functions.html) requirements for cv2.popylines for more details. \n\n-----------------\n\n**PointOnMap** is the class responsible for point rendering. \n\nAn instance is created provided three arguments:\n```\ngeo_rendering.PointOnMap(coordinates, weight, color)\n```\n\nThese arguments are used to instantiate properties of the instance:\n- .coordinates: the coordinates (in pixels) of the center of the point\n- .weight: the size of the point to render\n- .color: as a tuple of BGR color\n\nOther properties are set by default but can be edited at any time:\n- .origin coordinates (x_coord_or/y_coord_or)\n- .current coordinates (x_coord_curr/y_coord_curr): by default the same as the origin coordinates, unless the point should have an position interpolated using the dedicated method\n\nTwo methods are available: \n- render_point_on_map(base_map), that renders the point on the map file provided as an argument\n- interpolate_next_position(target_coords, tot_frames, curr_frame), used to interpolate the position of a point, knowing where we want it to arrive, in how many 'hops' ; especially used when rendering multiple frames for an animation\n\nSee [OpenCV ](https://docs.opencv.org/3.0-beta/modules/imgproc/doc/drawing_functions.html) requirements for cv2.circle for more details. \n\n-----------------\n\n**Projection** is the class responsible for calculating the conversion ratio and axis to use to center the map, from the coordinate system of the shapefile to the new coordinate system of the image file.\n\nAn instance is created provided three arguments:\n```\ngeo_rendering.Projection(map_to_scale, [margin])\n```\n\nThese arguments are used to instantiate properties of the instance:\n- .map_to_scale: the Map class instance object that we want to render\n- .margins [optional]: margins to add to (top, right, bottom, left) of the image file in pixels\n\n\nOther properties are set by default but can be edited at any time:\n- .image_size, an attribute of the map_to_scale\n- .map_max_bound / .map_min_bound: an attribute of the map_to_scale\n- .conversion: calculated using define_projection method\n- .axis_to_center: calculated using define_projection method\n\nThree methods are available: \n- define_projection(): calculates the conversion rate and axis on which to center the converted coordinates\n- apply_projection(coords, inverse=False): applies the conversion on coordinates ; the inverse argument allows to go from one coordinate system (the original one), to the new one\n- apply_translation(coords): translates the coordinates along the axis to center in order to center the map\n\n\n-----------------\n\n**ShapeFile** is the class responsible for converting a shapefile into a reader object and a dataframe.\n\nAn instance is created provided three arguments:\n```\ngeo_rendering.ShapeFile(file_path)\n```\n\nThese arguments are used to instantiate properties of the instance:\n- .shp_path, the path of the shapefile folder ; note that this folder should contain at least a .shp, .dbf and .shx in the same folder\n\nOther properties are set by default but can be edited at any time:\n- .shapefile, the shapefile reader object\n- .df_sf the information of the shapefile in the form of a dataframe\n- .shape_dict_sf: a dictionary of all shapes in the shapefile (key is the index of the shape, value a instance of the Shape class)\n\nFour methods are available: \n- sf_reader(path): creates a reader object from the shapefile folder\n- shp_to_df(): converts the shapefile reader to a dataframe\n- filter_shape_to_render(cond_stat, attr): filters out the dataframe using a particular column (attr) and a condition statement (cond_stat) ; cond_stat can be either a single string or a list of strings to match in the provide attr column\n- build_shape_dict(ref_df): constructs the dictionary using the id of each shape from the shapefile and instantiating instances of the Shape class for each of them ; it uses the dataframe extracted from the shapefile\n\nSee [PySHP](https://pypi.org/project/pyshp/) requirements for more details. \n\n\n-----------------\n\n**ShapeOnMap** is the class responsible for shape rendering. \n\nAn instance is created provided three arguments:\n```\ngeo_rendering.ShapeOnMap(shapefile, shape_id)\n```\n\nThese arguments are used to instantiate properties of the instance:\n- .shapefile: a Shapefile class instance\n- .shape_id: the id of the shape (can be assigned arbitrarily, but it is intended to be the same that the one used in the shapefile dataframe)\n\nOther properties are set by default but can be edited at any time:\n- .points: the coordinates of the boundaries of the shape\n- .center: the center coordinates of the shape\n- .max_bound / .min_bound: the extreme coordinates of the boundaries of the shape\n- .color_line (default white)\n- .line_thick (default 1)\n- .color_fill (default black)\n\nThree methods are available: \n- get_shape_coords(): calculates the points, center, max_bound / min_bound coordinates using the shapefile reader 'shape' attribute\n- project_shape_coords(projection): converts the coordinates of the shape using a given projection (conversion, axis_to_center), relying on the two projection methods apply_projection() and apply_translation()\n- fill_in_shape(map_to_render): renders the shape on the map file provided as an argument\n\n\nSee [OpenCV ](https://docs.opencv.org/3.0-beta/modules/imgproc/doc/drawing_functions.html) requirements for cv2.fillPolyfor more details. \n\n-----------------\n\n**Utils** is a class containing static methods used in other classes.\n\nThe three methods are:\n- calculate_centroid(points): computes the value of the center of a list of points\n- calculate_boundaries(points): returns the value of the max and min coordinates of the boundary delimited by the points\n- convert_id(idx, inverse=False): converts an index from one range [1-x] to another [0-x], or the inverse (if inverse=True)\n\n\n\nTest functions\n-----------------\n\nThere is a total of 37 tests available, that should cover most of the classes and methods available. \n\n\n| Name \t\t   | Stmts | Miss | Cover | Missing         |\n| ------------ | ----- | ---- | ----- | --------------- |\n| classfile.py | 214   |  10  |  95%  | 20-28, 155-156  |\n| utility.py   | 33    |   0  |  100% |\u00a0                |\n\nNote: tests can be executed using the following command from the geo_rendering main directory (where the setup.py file is stored!)\n\n```\npython setup.py test\n```\n\n\nFurther work and improvements\n-----------------------------\n\nSome improvements that could be performed on the package:\n\n- convert id should not go beyond 0\n- handle errors if points in calculate_boundaries are not lists of tuples (it doesn't make sense otherwise)\n- handle errors if points in calculate_centroid are not lists of tuples (it doesn't make sense otherwise)\n- handle errors if points to render on map is not a list of coordinates (type POLYGON)\n- format of input for interpolate_next_position\n- in general, handle better errors related to the format of an input\n\n\nSources, acknowlegments and related content\n-------------------------------------------\n\nThis work is inspired from a data visualisation project about the NYC taxi rides ([link to the repository of the project](https://github.com/acoullandreau/nyc_taxi_trips))",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/acoullandreau/geo_rendering_package",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "geo-rendering",
        "package_url": "https://pypi.org/project/geo-rendering/",
        "platform": "",
        "project_url": "https://pypi.org/project/geo-rendering/",
        "project_urls": {
            "Homepage": "https://github.com/acoullandreau/geo_rendering_package"
        },
        "release_url": "https://pypi.org/project/geo-rendering/1.0.0/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Rendering of images from a shapefile using OpenCV",
        "version": "1.0.0"
    },
    "last_serial": 5751335,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "ef85f180a43f6649eab725d466d47bf7",
                    "sha256": "b3f63c85cbbae3e13f8cb7d2c1cce435a7741dbd5830bf99b20504ba04c0bde6"
                },
                "downloads": -1,
                "filename": "geo_rendering-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "ef85f180a43f6649eab725d466d47bf7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 12222,
                "upload_time": "2019-08-29T11:07:13",
                "url": "https://files.pythonhosted.org/packages/8b/a4/98e8f783e2fac3e3ded6868e3dc4cc2bf74c07e7e9dc29fa02c1af051880/geo_rendering-1.0.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "ef85f180a43f6649eab725d466d47bf7",
                "sha256": "b3f63c85cbbae3e13f8cb7d2c1cce435a7741dbd5830bf99b20504ba04c0bde6"
            },
            "downloads": -1,
            "filename": "geo_rendering-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "ef85f180a43f6649eab725d466d47bf7",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 12222,
            "upload_time": "2019-08-29T11:07:13",
            "url": "https://files.pythonhosted.org/packages/8b/a4/98e8f783e2fac3e3ded6868e3dc4cc2bf74c07e7e9dc29fa02c1af051880/geo_rendering-1.0.0.tar.gz"
        }
    ]
}