Metadata-Version: 1.1
Name: PyCRS
Version: 0.1.2
Summary: GIS package for reading, writing, and converting between CRS formats.
Home-page: http://github.com/karimbahgat/PyCRS
Author: Karim Bahgat
Author-email: karim.bahgat.norway@gmail.com
License: MIT
Description: PyCRS
        =====
        
        PyCRS is a pure Python GIS package for reading, writing, and converting
        between various common coordinate reference system (CRS) string and data
        source formats.
        
        Introduction
        ------------
        
        Python should have a standalone GIS library focused solely on coordinate
        reference system metadata. That is, a library focused on the various
        formats used to store and represent crs definitions, including OGC WKT,
        ESRI WKT, Proj4, and various short-codes defined by organizations like
        EPSG, ESRI, and SR-ORG. Correctly parsing and converting between these
        formats is essential in many types of GIS work. For instance when trying
        to use PyProj to transform coordinates from a non-proj4 crs format. Or
        when wanting to convert the crs from a GeoJSON file to a .prj file. Or
        when simply adding a crs definition to a file that was previously
        missing one.
        
        When I created PyCRS, the only way to read and convert between crs
        formats was to use the extensive Python GDAL suite and its srs
        submodule, but the requirements of some applications might exclude the
        use of GDAL. There have also been some online websites/services, but
        these only allow partial lookups or one-way conversion from one format
        to another. I therefore hope that PyCRS will make it easier for
        lightweight applications to read a broader range of data files and
        correctly interpret and possibly transform their crs definitions.
        Written entirely in Python I also hope it will help clarify the
        differences between the various formats, and make it easier for more
        people to help keep it up-to-date and bug-free.
        
        Status
        ------
        
        Currently, the supported formats are OGC WKT (v1), ESRI WKT, Proj4, and
        any EPSG, ESRI, or SR-ORG code available from spatialreference.org. In
        the future I hope to add support for OGC URN identifier strings, and
        GeoTIFF file tags.
        
        The package is still in alpha version, so it will not perfectly parse or
        convert between all crs, and it is likely to have several (hopefully
        minor) differences from the results of other parsers like GDAL. In the
        source repository there is a tester.py script, which uses a barrage of
        commonly used crs as listed on
        http://www.remotesensing.org/geotiff/proj\_list/. Currently, the overall
        success rate for loading as well as converting between the three main
        formats is 70-90%, and visual inspections of rendering the world with
        each crs generally look correct. However, whether the converted crs
        strings are logically equivalent to each other from a mathematical
        standpoint is something that needs a more detailed quality check.
        
        Platforms
        ---------
        
        So far only tested on Python version 2.x, but should also be compatible
        with 3.x.
        
        Dependencies
        ------------
        
        Pure Python, no dependencies.
        
        Installing it
        -------------
        
        PyCRS is installed with pip from the commandline:
        
        ::
        
            pip install pycrs
        
        It also works to just place the "pycrs" package folder in an importable
        location like "PythonXX/Lib/site-packages".
        
        Example Usage
        -------------
        
        Begin by importing the pycrs module:
        
        ::
        
            import pycrs
        
        Reading
        ~~~~~~~
        
        The first point of action when dealing with a data source's crs is that
        you should be able to parse it correctly. In most situations this will
        mean reading the ESRI .prj file that accomponies a shapefile or some
        other file. PyCRS has a convenience function for doing that:
        
        ::
        
            fromcrs = pycrs.loader.from_file("path/to/shapefilename.prj")
        
        The same function also supports reading the crs from GeoJSON files:
        
        ::
        
            fromcrs = pycrs.loader.from_file("path/to/geojsonfile.json")
        
        If your crs is not defined in a file there are also functions for that.
        For instance if you know the url where the crs is defined you can do:
        
        ::
        
            fromcrs = pycrs.loader.from_url("www.somesite.com/someproj")
        
        Or if you are provided with the actual string representation of the crs,
        given by a web service for instance, you can load it using the
        appropriate function from the parser module or let PyCRS autodetect and
        load the crs type for you:
        
        ::
        
            fromcrs = pycrs.parser.from_unknown_text(somecrs_string)
        
        Converting
        ~~~~~~~~~~
        
        Once you have read the crs of the original data source, you may want to
        convert it to some other crs format. A common reason for wanting this
        for instance, is if you want to reproject the coordinates of your
        spatial data. In Python this is typically done with the PyProj module
        which only takes proj4 strings, so you would have to convert your
        datasource's crs to proj4:
        
        ::
        
            fromcrs_proj4 = fromcrs.to_proj4()
        
        You can then use PyCRS to define your target projection in the string
        format of your choice, before converting it to the proj4 format that
        PyProj expects:
        
        ::
        
            tocrs = pycrs.parser.from_esri_code(54030) # Robinson projection from esri code
            tocrs_proj4 = tocrs.to_proj4()
        
        With the source and target projections defined in the proj4 crs format,
        you are ready to transform your data coordinates with PyProj, which is
        not covered here.
        
        Writing
        ~~~~~~~
        
        After you transform your data coordinates you may also wish to save the
        data back to file along with the new crs. With PyCRS you can do this in
        a variety of crs format. For instance:
        
        ::
        
            with open("shapefile.prj", "w") as writer:
                writer.write(tocrs.to_esri_wkt())
        
        PyCRS also gives access to each crs element and parameter that make up a
        crs in the "elements" subpackage, so you could potentially also build a
        crs from scratch and then save it to a format of your choice. Inspect
        the parser submodule source code for inspiration on how to go about
        this.
        
        More Information:
        -----------------
        
        This tutorial only covered some basic examples. For the full list of
        functions and supported crs formats, check out the API Documentation.
        
        -  `Home Page <http://github.com/karimbahgat/PyCRS>`__
        -  `API Documentation <http://pythonhosted.org/PyCRS>`__
        
        License:
        --------
        
        This code is free to share, use, reuse, and modify according to the MIT
        license, see license.txt
        
        Credits:
        --------
        
        Karim Bahgat (2015)
        
        Changes
        -------
        
        0.1.2 (2015-08-05)
        ~~~~~~~~~~~~~~~~~~
        
        -  First official release
        
Keywords: GIS spatial CRS coordinates format
Platform: UNKNOWN
Classifier: License :: OSI Approved
Classifier: Programming Language :: Python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Scientific/Engineering :: GIS
