Commits

Anonymous committed 23a6b56

Update documentation.

Comments (0)

Files changed (1)

 =====
 osaic
 =====
-osaic is a simple module which let you create mosaics from images with
-a simple `python -mosaic foo.jpg` command.
+
+**osaic** is a simple python module which let you create mosaics from
+images by issuing a simple ``python -mosaic foo.jpg`` command.
+
+The basic idea is to take as input a set of images: the first is used as
+background for the final mosaic; the others are indexed by average
+colors and pated, as tiles, over the final mosaic.
+
+In addition, users are enabled to specify the final size of the mosaic
+(relative to the size of the initial target image) and the number of
+tiles to use per side.
 
 
 Dependencies
 ============
-osaic depends on the ``PIL`` library which is going to be installed
-automatically by the installation script: anyway, in order to make it
-possible to edit ``jpeg`` and ``png`` images, please install ``libjpeg``
-and ``libpng`` as well.
+
+The module depends on python ``PIL`` library (automatically fetched by
+the installation script) for all the operations concerning *image
+processing*. In addition, to add support for *jpeg*\s and *png*\s
+images, and to enable the module to display mosaics on screen, please
+install ``libjpeg``, ``libpng`` and ``libtk`` as well.  
 
 
 Install
 =======
+
+To install **osaic**, you are enabled to grab it from both the mercurial
+repository and from the Python Package Index (PyPI). The former is
+preferred for *bleeding-edge* users, even tough the latter is not
+guaranteed to be *very* stable as well.
+
+
+Mercurial
+---------
+
+From sources::
+
+    cd /wherever/you/want
+    hg clone https://bitbucket.org/iamFIREcracker/osaic
+    python setup.py install
+
+
+PyPI
+----
+
 From sources::
 
     cd /path/to/workspace
-    wget http://pypi.python.org/packages/source/o/osaic/osaic-1.2.1.tar.gz
-    tar zxvf osaic-1.2.1.tar.gz
-    cd osaic-1.2.1
+    wget http://pypi.python.org/packages/source/o/osaic/osaic-2.0.0.tar.gz
+    tar zxvf osaic-2.0.0.tar.gz
+    cd osaic-2.0.0
     python setup.py install
 
 From the PyPI::
 
 Usage
 =====
-osaic is a module that can be used either as a standalone application or
-as a standard python library.
+
+**osaic** is a module that can be used both as a standalone application
+and as a standard python module.
+
 
 Standalone application
 ----------------------
+
 A typical usage of the application is to display a mosaic composition
 created from a source image::
 
     python -mosaic image.jpg -o mosaic-image.jpg
 
 Finally, if you want to create a mosaic which is 4 times bigger than the
-original image, and with 100 tiles per axis, just issue::
+original image, and with 100 tiles per side, just issue::
 
-    python -mosaic -s4 -t100 image.jpg
+    python -mosaic -z4 -t100 image.jpg
 
 For everything else use the help message::
 
 
 Library
 -------
-First of all, import the module::
+
+The module is a collection of objects and functions with different
+capabilities: functions for vectors, color transformations, *image*
+objects, image indexes and procedure wrappers.
+
+Regarding operation with vectors, the module implement some basic
+functions not included in standard Python but useful while working with
+colors::
+
+    >>> dotproduct([1, 2, 3], [4, 5, 6])
+    70
+    >>> difference([1, 2, 3], [1, 2, 3])
+    [0, 0, 0]
+    >>> squaredistance([1, 2, 3], [0, 0, 0])
+    30
+
+It is possible to find also a couple of functions wrapping up common
+colors operations, like computation of the average color of an image and
+color quantization. The latter is particularly useful while trying to
+keep the CPU work load at low levels::
+
+    >>> average_color('almost-red.png')
+    (240, 10, 20)
+    >>> quantize_color((240, 10, 20), levels=2)
+    (192, 64, 64)
+
+As noted earlier, the module is built on top of the Python ``PIL``
+library. However, we chose not export such *external* objects, but
+rather present to users some wrappers, namely `ImageWrapper`::
+
+    >>> img = Image.open('foo.png')
+    >>> img.size
+    (640, 480)
+    >>> img.reratio(5 / 1)
+    >>> img.crop((0, 0, 10, 10))
+    >>> img.size
+    (10, 10)
+    >>> img.show()
+
+While creating mosaics, it comes in handy to have to possibility to
+index a set of images and make it possible to search which of them is
+the most similar, in terms of *average color*, to another one. The
+``ImageList`` object is shipped with the module for this reason::
+
+    >>> img_list = ImageList(['1.png', '2.png', '3.png'])
+    >>> img_list.search((255, 0, 0))
+    ImageTuple(filename='1.png', color=(255, 0, 0), image=None)
+
+Finally, the module is shipped with a ``mosaicify`` function which wraps
+up all the operations needed to create mosaic, including source images
+indexing, and search of neighbour images depending on the average
+color::
 
     >>> import osaic
-
-Then create a new ``Mosaic`` object::
-
-    >>> mos = osaic.Mosaic(['foo.jpg'], tiles=32, size=1)
-
-At this point, create the mosaic, show it on screen and save it on
-a file::
-
-    >>> mos.create()
-    >>> mos.show()
-    >>> mos.save('bar.jpg')
-
-Alternatively, you can use the ``create`` function shipped with the
-module which is a wrapper of all the actions listed above::
-
-    >>> import osaic
-    >>> osaic.create(
-    ...     filenames=['foo.jpg'],
-    ...     tiles=32,
-    ...     size=1,
-    ...     output=None,
+    >>> osaic.mosaificy(
+    ...     target='foo.png',
+    ...     sources=['bar.png', 'asd.png', 'bazinga.png'],
+    ...     tiles=128,
+    ...     zoom=4,
+    ...     output='mosaic.png',
     ... )
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.