m [ci skip]

hMatoba · Jan 30, 2015 · 8cf100e · 8cf100e
1 parent ba3fdf0
commit 8cf100e
Show file tree

Hide file tree

Showing 5 changed files with 305 additions and 0 deletions.
diff --git a/doc/about.rst b/doc/about.rst
@@ -0,0 +1,43 @@
+============
+About Piexif
+============
+
+What for?
+---------
+
+To simplify exif manipulations with python. Writing, reading, and more...
+
+Depends on
+----------
+
+Piexif doesn't depend on any 3rd module.
+
+Environment
+-----------
+
+Tested on Python 2.7, 3.3, 3.4, pypy, and pypy3. Piexif would run even on IronPython.
+
+License
+-------
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Hiroaki Matoba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/doc/appendices.rst b/doc/appendices.rst
@@ -0,0 +1,81 @@
+==========
+Appendices
+==========
+
+Exif Data in Piexif
+-------------------
+
+Each exif tag has appropriate type of the value. BYTE, ASCII, SHORT, or... See the document of Exif.
+http://www.kodak.com/global/plugins/acrobat/en/service/digCam/exifStandard2.pdf
+
++---------------+----------------------+
+| **Exif Type** | **Python Type(3.x)** |
++---------------+----------------------+
+| BYTE          | int                  |
++---------------+----------------------+
+| ASCII         | str                  |
++---------------+----------------------+
+| SHORT         | int                  |
++---------------+----------------------+
+| LONG          | int                  |
++---------------+----------------------+
+| RATIONAL      | (int, int)           |
++---------------+----------------------+
+| UNDEFINED     | bytes                |
++---------------+----------------------+
+| SRATIONAL     | (int, int)           |
++---------------+----------------------+
+
+If value type is number(BYTE, SHORT, LONG, RATIONAL, or SRATIONAL) and value count is two or more number, it is expressed with tuple.
+
++---------------------+-------------------------------+
+| BYTE, SHORT, LONG   | (int, int, ...)               |
++---------------------+-------------------------------+
+| RATIONAL, SRATIONAL | ((int, int), (int, int), ...) |
++---------------------+-------------------------------+
+
+Exif in piexif example is below.
+
+::
+
+    zeroth_ifd = {piexif.ZerothIFD.Make: u"Canon",  # ASCII, count any
+                  piexif.ZerothIFD.XResolution: (96, 1),  # RATIONAL, count 1
+                  piexif.ZerothIFD.YResolution: (96, 1),  # RATIONAL, count 1
+                  piexif.ZerothIFD.Software: u"piexif"  # ASCII, count any
+                  }
+    exif_ifd = {piexif.ExifIFD.ExifVersion: b"\x02\x00\x00\x00"  # UNDEFINED, count 4
+                piexif.ExifIFD.DateTimeOriginal: u"2099:09:29 10:10:10",  # ASCII, count 20
+                piexif.ExifIFD.LensMake: u"LensMake",  # ASCII, count any
+                piexif.ExifIFD.Sharpness: 65535,  # SHORT, count 1
+                piexif.ExifIFD.LensSpecification: ((1, 1), (1, 1), (1, 1), (1, 1)),  # Rational, count 4
+                }
+    gps_ifd = {piexif.GPSIFD.GPSVersionID: (2, 0, 0, 0),  # BYTE, count 4
+               piexif.GPSIFD.GPSAltitudeRef: 1,  # BYTE, count 1
+               }
+    exif_bytes = piexif.dump(zeroth_ifd, exif_ifd, gps_ifd)
+    
+    # round trip
+    piexif.insert(exif_bytes, "foo.jpg")
+    z, e, g = piexif.load("foo.jpg")
+
+On GoogleAppEngine
+------------------
+
+On GoogleAppEngine, it can't save files on disk. Therefore files must be handled on memory.
+
+::
+
+    jpg_data = self.request.get("jpeg")
+    output = io.BytesIO()
+
+    # load
+    zeroth_dict, exif_dict, gps_dict = piexif.load(jpg_data)
+    
+    # insert
+    piexif.insert(exif_bytes, jpg_data, output)
+
+    # remove
+    piexif.remove(jpg_data, output)
+
+    # transplant
+    piexif.transplant(jpg_data1, jpg_data2, output)
diff --git a/doc/functions.rst b/doc/functions.rst
@@ -0,0 +1,132 @@
+=========
+Functions
+=========
+
+.. warning:: It could set any value in exif without actual value. For example, actual XResolution is 300, whereas XResolution value in exif is 0. Confliction might happen.
+.. note:: This document is written for using Piexif on Python 3.x.
+
+
+load
+----
+.. py:function:: piexif.load(filename)
+
+   Return three IFD data that are 0thIFD, ExifIFD, and GPSIFD as dict.
+
+   :param str filename: JPEG or TIFF
+   :return: 0th IFD, Exif IFD, and GPS IFD
+   :rtype: dict, dict, dict
+
+::
+
+    zeroth_ifd, exif_ifd, gps_ifd = piexif.load("foo.jpg")
+    for key in zeroth_dict:
+        print(key, zeroth_ifd[key])
+    for key in exif_dict:
+        print(key, exif_ifd[key])
+    for key in gps_dict:
+        print(key, gps_ifd[key])
+
+.. py:function:: piexif.load(data)
+
+   Return three IFD data that are 0thIFD, ExifIFD, and GPSIFD as dict.
+
+   :param bytes data: JPEG or TIFF
+   :return: 0th IFD, Exif IFD, and GPS IFD
+   :rtype: dict, dict, dict
+
+dump
+----
+.. py:function:: piexif.dump(zeroth_ifd, exif_ifd, gps_ifd)
+
+   Return exif as bytes.
+
+   :param dict zeroth_ifd: 0th IFD as dict
+   :param dict exif_ifd: Exif IFD as dict
+   :param dict gps_ifd: GPS IFD as dict
+   :return: Exif
+   :rtype: bytes
+
+::
+
+    zeroth_ifd = {piexif.ZerothIFD.Make: u"Canon",
+                  piexif.ZerothIFD.XResolution: (96, 1),
+                  piexif.ZerothIFD.YResolution: (96, 1),
+                  piexif.ZerothIFD.Software: u"piexif"
+                  }
+    exif_ifd = {piexif.ExifIFD.DateTimeOriginal: u"2099:09:29 10:10:10",
+                piexif.ExifIFD.LensMake: u"LensMake",
+                piexif.ExifIFD.Sharpness: 65535,
+                piexif.ExifIFD.LensSpecification: ((1, 1), (1, 1), (1, 1), (1, 1)),
+                }
+    gps_ifd = {piexif.GPSIFD.GPSVersionID: (2, 0, 0, 0),
+               piexif.GPSIFD.GPSAltitudeRef: 1,
+               piexif.GPSIFD.GPSDateStamp: u"1999:99:99 99:99:99",
+               }
+    exif_bytes = piexif.dump(zeroth_ifd, exif_ifd, gps_ifd)
+    from PIL import Image
+    im = Image.open("foo.jpg")
+    im.thumbnail((100, 100), Image.ANTIALIAS)
+    im.save("out.jpg", exif=exif_bytes)
+
+
+insert
+------
+.. py:function:: piexif.insert(exif_bytes, filename)
+
+   Insert exif into JPEG.
+
+   :param bytes exif_bytes: Exif as bytes
+   :param str filename: JPEG
+
+::
+
+    exif_bytes = piexif.dump(zeroth_ifd, exif_ifd, gps_ifd)
+    piexif.insert(exif_bytes, "foo.jpg")
+
+.. py:function:: piexif.insert(exif_bytes, data, output)
+
+   Insert exif into JPEG.
+
+   :param bytes exif_bytes: Exif as bytes
+   :param bytes data: JPEG data
+   :param io.BytesIO output: ouput data
+
+remove
+------
+.. py:function:: piexif.remove(filename)
+
+   Remove exif from JPEG.
+
+   :param str filename: JPEG
+
+::
+
+    piexif.remove("foo.jpg")
+
+.. py:function:: piexif.remove(data, output)
+
+   Remove exif from JPEG.
+
+   :param bytes data: JPEG data
+   :param io.BytesIO output: output data
+
+transplant
+----------
+.. py:function:: piexif.transplant(filename1, filename2)
+
+   Transplant exif from filename1 to filename2.
+
+   :param str filename1: JPEG
+   :param str filename2: JPEG
+
+::
+
+    piexif.transplant("exif_src.jpg", "foo.jpg")
+
+.. py:function:: piexif.transplant(exif_src, image_src, output)
+
+   Transplant exif from exif_src to image_src.
+
+   :param bytes exif_src: JPEG data
+   :param bytes image_src: JPEG data
+   :param io.BytesIO output: output data
diff --git a/doc/index.rst b/doc/index.rst
@@ -0,0 +1,31 @@
+.. Piexif documentation master file, created by
+   sphinx-quickstart on Wed Jan 28 15:52:32 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Piexif's documentation!
+==================================
+
+To simplify exif manipulations with python. Writing, reading, and more... Piexif isn't a wrapper. To everywhere with Python.
+
+.. image:: https://travis-ci.org/hMatoba/Piexif.svg?branch=master
+   :target: https://travis-ci.org/hMatoba/Piexif
+.. image:: https://coveralls.io/repos/hMatoba/Piexif/badge.svg?branch=master
+   :target: https://coveralls.io/r/hMatoba/Piexif?branch=master
+.. image:: https://readthedocs.org/projects/piexif/badge/?version=latest
+   :target: https://readthedocs.org/projects/piexif/
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   installation
+   functions
+   appendices
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/installation.rst b/doc/installation.rst
@@ -0,0 +1,18 @@
+============
+Installation
+============
+
+.. note:: Piexif supports Python versions 2.7, 3.3, 3.4, Pypy, Pypy3
+
+
+'easy_install'::
+
+  $ easy_install piexif
+
+or 'pip'::
+
+  $ pip install --pre piexif
+
+or download .zip, extract it and run::
+
+  $ python setup.py install