Metadata-Version: 2.4
Name: PyBNG
Version: 0.2.0
Summary: A library to convert BNG/OSNG coordinates 
Home-page: https://github.com/ThunderStruct/PyBNG
Author: Mohamed Shahawy
Author-email: envious-citizen.0s@icloud.com
Keywords: gis mapping coordinates grid-reference mapping ordiance-survey lat-long bng all-numeric
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Other Audience
Classifier: Topic :: Education
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: OSGridConverter
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PyBNG
[![Build Status](https://travis-ci.org/ThunderStruct/PyBNG.svg?branch=master)](https://travis-ci.org/ThunderStruct/PyBNG) [![pypi](https://img.shields.io/badge/pypi%20package-0.2.0-lightgrey.svg)](https://pypi.org/project/PyBNG/0.2.0/) [![Python](https://img.shields.io/badge/python-3.5^-blue.svg)](https://github.com/ThunderStruct/PyBNG) [![License](https://img.shields.io/cocoapods/l/AFNetworking.svg)](https://github.com/ThunderStruct/PyBNG/blob/master/LICENSE)

An Ordinance-Survey National Grid coordinates converter

------------------------

## Getting Started
PyBNG is built on top of [OSGridConverter](https://github.com/jdstmporter/OSGridConverter/) and is used to convert coordinates from the Ordnance Survey National Grid system (often called the British National Grid -- *BNG*) to latitude and longitude using `WGS84` (other geodetic reference systems available).

While OSGridConverter can convert BNG to latitude and longitude, it does not support all-numeric grid references, which is the primary feature in this library.

### Installation
#### PIP (recommended)

```sh
pip install PyBNG
```
#### Manual Installation
Simply clone the entire repo and extract the files in the `PyBNG` folder, then copy all the content to your project folder

Or use one of the shorthand methods below
##### GIT
  - `cd` into your project directory
  - Use `sparse-checkout` to pull the library files only into your project directory
    ```sh
    git init PyBNG
    cd PyBNG
    git remote add -f origin https://github.com/ThunderStruct/PyBNG.git
    git config core.sparseCheckout true
    echo "PyBNG/*" >> .git/info/sparse-checkout
    git pull --depth=1 origin master
    ```
   - Import the newly pulled files into your project folder

##### SVN
  - `cd` into your project directory
  - `checkout` the library files
    ```sh
    svn checkout https://github.com/ThunderStruct/PyBNG/trunk/PyBNG
    ```
  - Import the newly checked out files into your project folder
  

### Usage
#### Initialization
A `PyBNG` object can be instantiated as follows:

```python
from PyBNG import PyBNG

bng = PyBNG(easting=519080, northing=185050)

latlon = PyBNG(lat=51.55178424773851, lon= -0.2835125528796557)
```
The initializer expects `easting` and `northing` *OR* `lat` and `lon` parameters, depending on the required conversion


### Methods

  - `get_latlon(datum='WGS84')`:
    - Description: calculates the latitude and logitude based on the given BNG coordinates
    - Parameters: none (passed to constructor)
    - Return Value: tuple -- (latitude, longitude)
    - Usage: 
        ```python
        from PyBNG import PyBNG

        bng = PyBNG(easting=519080, northing=185050)
        bng.get_latlon()     # (51.55178424773851, -0.2835125528796557)
        ```
  - `get_bng(datum='WGS84')`:
    - Description: calculates the BNG coordinates given a latitude and a longitude
    - Parameters: none (passed to constructor)
    - Return Value: typle -- (easting, northing)
    - Usage: 
        ```python
        from PyBNG import PyBNG

        latlon = PyBNG(lat=51.55178424773851, lon= -0.2835125528796557)
        latlon.get_bng()     # (519107, 185051)
        ```
*Please note that converting BNG coordinates to latitude/longitude and back to BNG will yield different results due to internal float rounding*

### Acknowledgment
I would like to thank [Dr. Lakshmi Babu-Saheer](mailto:lakshmi.babu-saheer@anglia.ac.uk) for her unwavering support, encouragement, and advice. 

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/ThunderStruct/PyBNG/blob/master/LICENSE) file for details


