## **gpsphoto.py**

Module that uses ExifRead and piexif to extract, modify and strip GPS Tag Data 
from jpeg and tiff format photos.
This module was made possible by the ExifRead, piexif, and Pillow (PIL) modules.

## **Installation**

### **PyPI**
The recommended process is to install the 
  [PyPI package GPSPhoto](https://pypi.python.org/pypi/GPSPhoto "GPSPhoto")
  as it allows easily staying up to date::
```
pip install gpsphoto
pip3 install gpsphoto
```    
See the [pip documentation](https://pip.pypa.io/en/latest/user_guide.html) 
for more info.

## **Compatibility**

GPSPhoto.py was tested on the following Python versions:

- 2.7.12
- 3.5.2

Should be compatible where webbrowser, piexif, ExifRead, 
and Pillow are available.

## **Usage**

### **Command Line**

Some examples:
```
  Usage:
    python gpsphoto.py <options> "/path/to/1st/photo" "/path/to/2nd/photo" ...

  Options:
    -H - This Help Menu
    -D - Output Raw Data
    -O <image to open> - Opens Image in Google Maps'
    -E latitude longitude GoogleApiKey -  returns elevation
    -S <image to strip> <new image> - Strips GPS Data
        alt=int date=YYYY:MM:DD time=HH:MM:SS \
        stamp="YYYY:MM:DD HH:MM:SS" key=<ApiKey>
        alt is optional - will default to 0
        stamp is optional - will default to now
        date is optional - do not use with time, use stamp
        time is optional - do not use with date, use stamp
        key is optional - use if you want auto elevation

Example:
    python gpsphoto.py -E 35.104860 -106.628915 <some-key>
    python gpsphoto.py -S /path/to/image /path/to/newImage
    python gpsphoto.py -M /path/to/image /path/to/newImage
        lat=35.104860 lon=-106.628915 alt=1765 \
        stamp="1989:05:29 06:01:00"

    Sample Debug Output:

        GPS GPSTimeStamp: [16, 12, 28]
        Image GPSInfo: 504
        GPS GPSLongitude: [106, 34, 585371/10000]
        GPS GPSDate: 2016:10:01
        GPS GPSLatitudeRef: N
        GPS GPSLatitude: [35, 3, 95521/5000]
        GPS GPSProcessingMethod: ASCII
        GPS GPSLongitudeRef: W
        GPS GPSAltitudeRef: 0
        GPS GPSAltitude: 1636
```


### **Python Script**
```
from GPSPhoto import gpsphoto
# Get the data from image file and return a dictionary
data = gpsphoto.getGPSData('/path/to/image.jpg')
rawData = gpsphoto.getRawData('/path/to/image.jpg')

# Print out just GPS Data of interest
for tag in data.keys():
    print "%s: %s" % (tag, data[tag])

# Print out raw GPS Data for debugging
for tag in rawData.keys():
    print "%s: %s" % (tag, rawData[tag])

# Create a GPSPhoto Object
photo = gpsphoto.GPSPhoto()
photo = gpsphoto.GPSPhoto("/path/to/photo.jpg")

# Create GPSInfo Data Object
info = gpsphoto.GPSInfo((35.104860, -106.628915))
info = gpsphoto.GPSInfo((35.104860, -106.628915), \
          timeStamp='1970:01:01 09:05:05')
info = gpsphoto.GPSInfo((35.104860, -106.628915), \
          alt=10, timeStamp='1970:01:01 09:05:05')

# Modify GPS Data
photo.modGPSData(info, '/path/to/newFile.jpg')

# Strip GPS Data
photo.stripData('/path/to/newFile.jpg')
```
    
### **Class and Function Definitions**
```
class GPSInfo(__builtin__.object)
|  Object to represent GPS Data to be added or modified to Image File
|
|  Methods defined here:
|
|  __init__(self, coord, alt=0, timeStamp=None)
|      GPSInfo(coord, alt, timeStamp)
|      Constructor takes three arguments
|          coord     - tuple or list of two floats representing the gps
|                      coordinates i.e. (35.104860, -106.628915)
|          alt       - int representing altitude, defaults to 0
|          timeStamp - str or datetime representing date and time
|                      i.e. '1970:01:01 09:05:05', defaults to None
|
|  getAlt(self)
|      Returns alt - represents altitude or elevation
|
|  getCoord(self)
|      Returns coord - represents gps coordinates
|
|  getDateTime(self)
|      Returns datetime object timeStamp
|
|  getGPSFormattedDate(self)
|      Returns GPS Formatted Time in tuple of tuples form
|      i.e. ((18, 1), (29, 1), (22,1))
|
|  getGPSFormattedTime(self)
|      Returns GPS Formatted Date in str form
|      i.e. '1970:05:01'
|
|  getTimeStamp(self)
|      Returns str of timeStamp -  represents timeStamp
|
|  setAlt(self, alt)
|      setAlt(alt)
|
|      Sets alt, takes one argument
|          alt - int or float representing altitude or elevation
|
|  setCoord(self, coord)
|      setCoord(coord)
|
|      Sets coord, takes one argument
|          coord - tuple or list of two floats i.e. (35.104860, -106.628915)
|
|  setTimeStamp(self, timeStamp)
|      setTimeStamp(timeStamp)
|
|      Sets timeStamp, takes one argument
|          timeStamp - None, str or datetime representing time and date,
|                      None will default to time now
|
|  ----------------------------------------------------------------------
|  Data descriptors defined here:
|
|  __dict__
|      dictionary for instance variables (if defined)
|
|  __weakref__
|      list of weak references to the object (if defined)
|
|  alt
|      Returns alt - represents altitude or elevation
|
|  coord
|      Returns coord - represents gps coordinates
|
|  timeStamp
|      Returns str of timeStamp -  represents timeStamp

class GPSPhoto(__builtin__.object)
|  GPSPhoto(object) -> GPSPhoto Object
|
|  Creates an Object for the modification, extraction, and removal of GPS Exif
|  Tag info on JPEG and Tiff formatted images
|
|  Methods defined here:
|
|  __init__(self, filename='')
|      Constructor - Takes String argument defaults to empty string
|
|      if argument is passed in will initialize object with filename
|      example:
|          GPSPhoto("test.jpg")
|          or
|          GPSPhoto()
|
|  coord2decimal(self, coord, quad)
|      coord2decimal(coord, quad)
|
|      Converts Degrees, Minutes and Seconds to decimal.
|
|      Arguments:
|          coord - tuple or list consisting of degree, minute, and second or
|                  degree and minute.
|          quad  - str reference of the character 'N','S','E','W'
|                  representing North, South, East, West. This also specifies
|                  latitude or longitude
|
|  decimal2Degree(self, coord)
|      decimal2Degree(coord)
|
|      Convert Decimal Coordinates to Degrees, Minutes, Seconds
|      and determines Quadrant, takes one argument
|          coord - tuple or list of 2 floats
|
|      Returns a dictionary of latitude and longitude
|
|  getGPSData(self)
|      Returns GPS Data Dictionary
|
|  getRawData(self)
|      Returns Raw GPS Exif Data
|
|  loadFile(self, filename)
|      loadFile(filename)
|
|      Loads Image file for extraction takes one argument
|          filename - str of the path/to/imagefile
|
|  modGPSData(self, gpsInfo, newFileName)
|      modGPSData(coord, newFileName, alt)
|
|      Modifies GPS Data, takes three arguments
|          coord       - a list or tuple of (latitude,longitude)
|          newFileName - str of /path/to/newImageFile
|          alt         - int or float of the altitude
|
|  stripData(self, newFileName)
|      stripData(newFileName)
|
|      Strips all exif data from photo and saves to new jpeg,
|      takes one argument
|          filename - str of /path/to/newImageFile
|
|  ----------------------------------------------------------------------
|  Data descriptors defined here:
|
|  __dict__
|      dictionary for instance variables (if defined)
|
|  __weakref__
|      list of weak references to the object (if defined)
|
|  gpsData
|      Returns GPS Data Dictionary
|
|  rawData
|      Returns Raw GPS Exif Data

coord2decimal(coord, quad)
  coord2decimal(coord, quad)
      
  Converts Degrees, Minutes and Seconds to decimal.
      
  Arguments:
    coord - tuple or list consisting of degree, minute, and second or
            degree and minute.
    quad  - str reference of the character 'N','S','E','W'
            representing North, South, East, West. This also specifies
            latitude or longitude

decimal2Degree(coord)
  decimal2Degree(coord)
      
  Convert Decimal Coordinates to Degrees, Minutes, Seconds
  and determines Quadrant, takes one argument
     coord - tuple or list of 2 floats
      
  Returns a dictionary of latitude and longitude

getGPSData(fileName)
  getGPSData(filename)
  Gets GPS Data from Image, takes one argument
    fileName - str of path/to/image
      
  There are 3 different types of Longitude and Latitude data stored.
        1 - type is already in decimal format
            Assumption no Ref Value
        2 - type is in degree and minute format
            Assumption [100, 44.5678]
        3 - type is in degree, minute and second
            Assumption [100, 44,95521/5000]
  This function will assume the assumptions are correct and parse the
  strings and return a list of floating elements, takes an parameter of
  list of strings

getRawData(fileName)
  getRawData(fileName)
  Returns the raw GPS Data returned from ExifRead, takes one argument
    fileName - str of path/to/image

stripGPSData(oldFile, newFile)
  stripGPSData(oldFile, newFile)
      
  Strips all exif data from photo and saves to new jpeg, takes two arguments
    oldFile - str of /path/to/image of image to be stripped
    newFile - str of /path/to/image of the new stripped image
```
