{
    "info": {
        "author": "Philip Griffith",
        "author_email": "philip.griffith@fsu.edu",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3.6"
        ],
        "description": "# PyUTM\n\nPyUTM is a Python package that creates standardized grid references for point data.\nIt can also use those grid references to create spatially meaningful unique identifiers for tasks such as asset naming.\n\nGrid references can be created in the following formats:\n- United States National Grid (USNG)\n- Military Grid Reference System (MGRS)\n- Universal Transverse Mercator (UTM)\n\n[Click here](https://docs.google.com/presentation/d/e/2PACX-1vS2LmQtJuGn2tv4mggu2QjJloEUQ99NRmn5kFx69lLIlsYfkhg0bJb_BEpFO8LK8rM4rqx33N_IRxWW/pub?loop=false&delayms=3000) for the slides from the [SHRUG 2018](http://shrug-gis.org/workshop/2018/) presentation on this package.\n\n### Version 0.2.1\n\nThe following features are currently in development, but not yet supported in the current version:\n- Locations requiring UPS grid references\n- Exceptions to grid zones in UTM\n\n## Table of Contents\n\n[What is a grid reference?](#what-is-a-grid-reference)\n\n- [Reading a USNG or MGRS grid reference](#reading-a-usng-or-mgrs-grid-reference)\n\n[What is a unique identifier?](#what-is-a-unique-identifier)\n\n[Examples](#examples)\n\n- [Create a Grid object](#1-create-a-grid-object)\n- [Call the write_refs() method](#2-call-the-write_refs-method)\n- [Call the write_uids() method](#3-call-the-write_uids-method)\n- [Call the write_utm() method](#4-call-the-write_utm-method)\n\n[References](#references)\n\n### What is a grid reference?\n\nBased on the Universal Transverse Mercator (UTM) and Universal Polar Stereographic (UPS) map projections,\n**a grid reference allows any location in the world to be described by a string of up to 15 characters**.\nThe precision of a location increases as characters are added to its grid reference and\ndecreases as characters are removed.\n\nThe following are all valid examples of grid references at different levels of precision:\n- 18LVJ\n- 12JXQ69\n- 30UWB8270\n- 36RUU203175\n- **33MXS97396762**\n- 44RKR0691609280\n\nThe **first set** of characters in a grid reference describes its **Grid Zone Designation** (GZD).\n- This is usually three characters long and is comprised of a number between 1 and 60 followed by a letter: **33M**.\n- By default, PyUTM adds a leading zero to numbers less than 10: **02U**.\n- With some exceptions in the northern latitudes and at the poles, the GZD describes a standard area encompassing\n6\u00c2\u00b0 of longitude and 8\u00c2\u00b0 of latitude.\n- The letters 'I' and 'O' are omitted to avoid confusion with the numbers '1' and '0'.\n\nThe **second set** of characters in a grid reference describes its **100 kilometer square** within the GZD.\n- This is always two characters long and is comprised of two letters, again omitting 'I' and 'O': **XS**.\n- Though the majority of squares within a GZD are 100 km on each side, those located on the edges of the GZD can be\nsmaller in area, due to the [conformal nature of the projections](https://en.wikipedia.org/wiki/Conformal_map_projection)\nfrom which the grid references are derived.\n\nThe **third and fourth sets** of characters in a grid reference describe its distance in meters from the lower left\ncorner of the 100 km square. The third set of characters describes the **location's distance east** of the lower left corner (its *easting*),\nwhile the fourth set of characters describes the **location's distance north** of the lower left corner (its *northing*).\n- Both sets can be between zero and five characters long and are comprised entirely of digits; they must have the same\nnumber of characters and are not separated by a space: **97396762** represents a location of **9739 easting** and **6762 northing**.\n- The number of digits used in each set determines the number of meters that those digits represent. As the number of\ndigits increases from zero to five, so does the precision with which a location can be established within the 100 km square:\n\nNumber of Digits | Precision in Meters | Size of Location\n:---: | :---: | :---:\nZero | 100 000 | Regional Area\nOne | 10 000 | Local Area\nTwo | 1 000 | Neighborhood\nThree | 100 | Football Field\nFour | 10 | House\nFive | 1 | Bath towel\n\n### Reading a USNG or MGRS grid reference\n\nTo locate the area described by a grid reference, break the grid reference down into its component sets\nthen read from left to right.\n\nFor example, the grid reference **52JGS0495** contains the following sets:\n- Grid Zone Designation: 52J\n- 100 km square: GS\n- Distance: 0495\n  - Easting: 04\n  - Northing: 95\n\nThis grid reference therefore describes a location...\n\n- ...within grid zone **52J**...\n\n![grid_zone](docs/images/gzd.JPG)\n\n- ...that is within the 100 km square **GS**.\n\n![100km](docs/images/100km.JPG)\n\n- Because the easting and northing contain **two** digits, they describe a location with a precision of 1,000 meters (1 km),\nfound **4 km east** and **95 km north** of the 100 km square's lower left corner:\n\n![distance](docs/images/dist.JPG)\n\n- Here we see the location described by 52JGS0495: [Uluru](https://en.wikipedia.org/wiki/Uluru).\n\n![location](docs/images/location.JPG)\n\nNote that the grid reference does **not** describe the **point** where the easting and northing cross,\nbut rather the **entire 1 km square** to the northeast of that point.\nTo describe a smaller area, we would add digits to the distance, thereby increasing its precision.\n\n### What is a unique identifier?\n\nA unique identifier (UID) modifies a point's grid reference by adding a numeric suffix to insure that **each reference-based ID\nwithin the dataset is unique**, even when two points may share the same grid reference.\nIt can add prefixes to the reference to make the UID more meaningful or remove character sets from the standard grid\nreference to make a UID shorter; it also adds a delimiter between the character sets to improve readability.\n  - **M-XS-9739-6762-3** is a UID containing both a custom prefix and numeric suffix;\nthe GZD has not been used and delimiters have been added to separate the character sets.\n\n## Examples\n\nTo install PyUTM, use PyPI:\n```\npip install pyutm\n```\n*N.B. Python 2.7 Windows users may need to install the\n[Microsoft Visual C++ Compiler for Python 2.7](https://www.microsoft.com/en-us/download/details.aspx?id=44266)\nbefore using this package.*\n\n### 1. Create a `Grid()` object\n\n`Grid(data, columns=None, epsg=4326)`\n\n- `data`: the point data used to construct the grid references and UIDs\n  - The data can be either a list of coordinates or a file path to a CSV or shapefile\n  - Lists should be in the following format: `[(X coordinate, Y coordinate), ...]`\n- `columns`: if the data is in CSV format, these are the columns that hold the coordinates\n  - The argument should be passed in the following format: `[X coordinate, Y coordinate]`\n- `epsg`: the EPSG number of the data's coordinate reference system\n  - The default EPSG is **4326** (WGS 84)\n\n ```python\n>>> import pyutm\n# Create a grid object from a list of longitudes and latitudes\n>>> lonlat = [(16.776031, -3.005612), (16.772291, -3.007136)]\n>>> grid_from_list = pyutm.Grid(lonlat)\n# Create a grid object from a CSV file\n>>> grid_from_csv = pyutm.Grid('my_points.csv', columns=['LON', 'LAT'])\n# Create a grid object from a shapefile in WGS 84 Web Mercator (Auxiliary Sphere)\n>>> grid_from_shp = pyutm.Grid('my_points.shp', epsg=3857)\n```\n\n### 2. Call the `write_refs()` method\n\nIf a file name is specified, this function writes the grid **ref**erence of each point to the file.\nIf the input data is in the CSV or shapefile format, the grid references are added as a new column to the file.\n\nThis function always returns a list in the form `[[X, Y, 'Grid Reference'], ...]`.\n\n`write_refs(fname=None, column='GRID_REF', precision=10)`\n\n- `fname` *(optional)*: the name of the file to which the grid references are written\n  - The output file must be in the same format as the input data\n- `column`: the header of the column to which the grid references are written\n  - The default column name is **GRID_REF** \n- `precision`: the desired precision of the grid references, in meters\n  - The default precision is **10 meters**\n\n```python\n>>> lonlat = (16.776031, -3.005612)\n>>> my_grid = pyutm.Grid(lonlat)\n# Create grid references\n>>> my_ref = my_grid.write_refs()\n>>> my_ref\n[[16.776031, -3.005612, '33MXS97386762']]\n# Specify the precision of the grid reference\n>>> my_1m_ref = my_grid.write_refs(precision=1)\n>>> my_1m_ref\n[[16.776031, -3.005612, '33MXS9738967626']]\n# Create grid references from a CSV file\n>>> grid_from_csv = pyutm.Grid('my_points.csv', column=['LON', 'LAT'])\n# Write the grid references to a new CSV with a custom column name\n>>> grid_from_csv.write_refs('my_refs.csv', column='MY_REFS')\n# Create grid references from a shapefile\n>>> grid_from_shp = pyutm.Grid('my_points.shp')\n# Write the grid references to a new shapefile with 10 km precision\n>>> grid_from_shp.write_refs('my_refs.shp', precision=10000)\n```\n\n### 3. Call the `write_uids()` method\n\nIf a file name is specified, this function writes the **u**nique **id**entifiers of each point to the file.\nIf the input data is in the CSV or shapefile format, the UIDs are added as a new column to the file.\n\nThis function always returns a list in the form `[[X, Y, 'UID'], ...]`.\n\n`write_uids(fname=None, column='UID_REF', precision=10, prefix=None, prefix_column=None, gzd=True, k100=True, delimiter='-')`\n\n- `fname` *(optional)*: the name of the file to which the UIDs are written\n  - The output file must be in the same format as the input data\n- `column`: the header of the column to which the UIDs are written\n  - The default column name is **UID_REF** \n- `precision`: the desired precision of the UIDs, in meters\n  - The default precision is **10 meters**\n- `prefix`: the prefix to be added to all UIDs\n- `prefix_column`: the name of the data column containing prefix characters\n- `gzd`: whether to include the Grid Zone Designation in the UIDs\n  - The default is **True**\n- `k100`: whether to include the 100 kilometer square in the UIDs\n  - The default is **True**\n  - If `k100` is set to False, `gzd` is also set to False\n- `delimiter`: the character(s) used to separate the character sets\n  - The default character is a dash: **-**\n\n```python\n>>> lonlat = (16.776031, -3.005612)\n>>> my_grid = pyutm.Grid(lonlat)\n# Create unique identifiers\n>>> my_uid = my_grid.write_uids()\n>>> my_uid\n[[16.776031, -3.005612, '33M-XS-9738-6762-1']]\n# Increase the precision, add a prefix to the UID, remove the GZD and change the delimiter\n>>> my_prefix = my_grid.write_uids(precision=1, prefix='m', gzd=False, delimiter=':')\n>>> my_prefix\n[[16.776031, -3.005612, 'm:XS:97389:67626:1']]\n# Create UIDs from a CSV file\n>>> grid_from_csv = pyutm.Grid('my_points.csv', column=['LON', 'LAT'])\n# Add prefixes to the UIDs using values in a column of the input CSV,\n# then write the UIDs to a new CSV with a custom column name\n>>> grid_from_csv.write_refs('my_uids.csv', column='MY_UIDS', prefix_column='MY_PREFIXES')\n# Create UIDs from a shapefile\n>>> grid_from_shp = pyutm.Grid('my_points.shp')\n# Add prefixes to the UIDs using values in a column of the input shapefile\n# and decrease the precision, then write the UIDs to a new shapefile.\n>>> grid_from_shp.write_refs('my_uids.shp', precision=1000)\n```\n\n### 4. Call the `write_utm()` method\n\n:hammer_and_wrench: *Coming soon* :hammer_and_wrench:\n\n## References\n\nNational Geospatial-Intelligence Agency, *The Universal Grids and the Transverse Mercator and Polar Stereographic Map Projections*,\n[NGA Standardization Document NGA.SIG.0012_2.0.0_UTMUPS](http://earth-info.nga.mil/GandG/publications/NGA_SIG_0012_2_0_0_UTMUPS/NGA.SIG.0012_2.0.0_UTMUPS.pdf).\nWashington, D.C.: Office of Geomatics, 2014.\n- PyUTM will eventually implement the logic found in Sections 11, 12 and 14 of this document.\n\nNational Geospatial-Intelligence Agency, *Universal Grids and Grid Reference Systems*,\n[NGA Standardization Document NGA.STND.0037_2.0.0_GRIDS](http://earth-info.nga.mil/GandG/publications/NGA_STND_0037_2_0_0_GRIDS/NGA.STND.0037_2.0.0_GRIDS.pdf).\nWashington, D.C.: Office of Geomatics, 2014.\n- Though broader in scope than the previous document, Chapter 3 and Appendices A and B are particularly helpful.\n- PyUTM currently implements a version of the logic found in Appendix B of this document.\n\nNational Geospatial-Intelligence Agency, Office of Geomatics, [Coordinate Systems Data](http://earth-info.nga.mil/GandG/update/index.php?action=home#tab_coord-data).\n- A repository of worldwide GIS layers for the UTM and MGRS coordinate systems\n\n\n",
        "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/FREAC/pyutm",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "pyutm",
        "package_url": "https://pypi.org/project/pyutm/",
        "platform": "",
        "project_url": "https://pypi.org/project/pyutm/",
        "project_urls": {
            "Homepage": "https://github.com/FREAC/pyutm"
        },
        "release_url": "https://pypi.org/project/pyutm/0.2.1/",
        "requires_dist": [
            "numpy",
            "pandas",
            "pyshp",
            "pyproj"
        ],
        "requires_python": "",
        "summary": "Creates standardized grid references, unique identifiers and UTM coordinates for point data.",
        "version": "0.2.1"
    },
    "last_serial": 4487120,
    "releases": {
        "0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "42d3882be2383188ece4d3fe9eb97d79",
                    "sha256": "a67c600295b424fc9238e675d8e3192580c7ce6ae67ccb6c22c640acef62c2f2"
                },
                "downloads": -1,
                "filename": "pyutm-0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "42d3882be2383188ece4d3fe9eb97d79",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 14022,
                "upload_time": "2018-10-26T19:44:39",
                "url": "https://files.pythonhosted.org/packages/6a/cf/b16370fb809e8836877a852abe8a5b48d24ee782b901d68a422e9c28666e/pyutm-0.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "de9fc187f4873ff240c7abf119f91645",
                    "sha256": "326f07a5a4289a0f20885d3f61d551d9aedc606769fac3d43a1c6b49ff6c2828"
                },
                "downloads": -1,
                "filename": "pyutm-0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "de9fc187f4873ff240c7abf119f91645",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16743,
                "upload_time": "2018-10-26T19:44:41",
                "url": "https://files.pythonhosted.org/packages/0e/1b/8a83089981d3c35d60748f459cbfe1de980983c71e16ff07b9b41b4813b4/pyutm-0.1.tar.gz"
            }
        ],
        "0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "62808e2da770229a0b66110cb708f108",
                    "sha256": "82dba22eb83f84b8368738234e3ab50e8683b35e09495f68f354ac97f78ddd02"
                },
                "downloads": -1,
                "filename": "pyutm-0.2-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "62808e2da770229a0b66110cb708f108",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 14403,
                "upload_time": "2018-11-14T21:05:13",
                "url": "https://files.pythonhosted.org/packages/e1/a0/6aaa220e8de9a3d947d52c0051e42e9794cc21249ff8843acd47b1a2d7c2/pyutm-0.2-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "c46650d08a167244ca9a5ec1c521d8c7",
                    "sha256": "44bdc3886a5f24daa78ddd6e0398018b8263bb803cee2b6ed223575146810a29"
                },
                "downloads": -1,
                "filename": "pyutm-0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "c46650d08a167244ca9a5ec1c521d8c7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17263,
                "upload_time": "2018-11-14T21:05:14",
                "url": "https://files.pythonhosted.org/packages/cb/ed/9ad8e8d2e0df67e2aab06b7b781b7ac032096002f42ed31eeb88d79e96f2/pyutm-0.2.tar.gz"
            }
        ],
        "0.2.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "02bd1b6af61b92f307d64d9d18649abc",
                    "sha256": "4691d39103e812b2d5a447d6c86c5d44a0d72e883133a9b52daf87e39ebbf547"
                },
                "downloads": -1,
                "filename": "pyutm-0.2.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "02bd1b6af61b92f307d64d9d18649abc",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 14420,
                "upload_time": "2018-11-14T21:34:52",
                "url": "https://files.pythonhosted.org/packages/01/4c/590bf0f250685c66c23d60017744626e3a252f5ae020f1816d6c397d1532/pyutm-0.2.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "1bea825b07d3a902401bf963af311969",
                    "sha256": "f2e788e7b94ce21e1dcc166dfc9c5c8d6cf07b65596b4ba0e31109b67caeb1e7"
                },
                "downloads": -1,
                "filename": "pyutm-0.2.1.tar.gz",
                "has_sig": false,
                "md5_digest": "1bea825b07d3a902401bf963af311969",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17242,
                "upload_time": "2018-11-14T21:34:53",
                "url": "https://files.pythonhosted.org/packages/b2/d2/62647bcf37828d143591a905c6e2b46234a4583d997b9f303b02a3346925/pyutm-0.2.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "02bd1b6af61b92f307d64d9d18649abc",
                "sha256": "4691d39103e812b2d5a447d6c86c5d44a0d72e883133a9b52daf87e39ebbf547"
            },
            "downloads": -1,
            "filename": "pyutm-0.2.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "02bd1b6af61b92f307d64d9d18649abc",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 14420,
            "upload_time": "2018-11-14T21:34:52",
            "url": "https://files.pythonhosted.org/packages/01/4c/590bf0f250685c66c23d60017744626e3a252f5ae020f1816d6c397d1532/pyutm-0.2.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "1bea825b07d3a902401bf963af311969",
                "sha256": "f2e788e7b94ce21e1dcc166dfc9c5c8d6cf07b65596b4ba0e31109b67caeb1e7"
            },
            "downloads": -1,
            "filename": "pyutm-0.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "1bea825b07d3a902401bf963af311969",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 17242,
            "upload_time": "2018-11-14T21:34:53",
            "url": "https://files.pythonhosted.org/packages/b2/d2/62647bcf37828d143591a905c6e2b46234a4583d997b9f303b02a3346925/pyutm-0.2.1.tar.gz"
        }
    ]
}