Author: Ryan Haigh
Revision Date: 2008-11-08 19:41:11 UTC

After testing on both Windows and Linux it was determined that the tkinter
toolkit (upon which easygui is based) produced GUI dialogs that were...well
UGLY. This was particularly evident on the Linux platform. To address this
issue the graphical toolkit used by the application has been changed to
wxPython.

The dialogs script has been created to provide a library of simple common
dialogs similar to that provided by the easygui script which it replaces. By
using this external script the simplicity of the GUI related code in the main
sort2size script is maintained and only minor modifications have been made.

Testing of the application on both platforms using the new dialogs has shown
the wxPython toolkit to be far superior to tkinter, producing widgets that
appear native on both platforms. The only downside has been an increase in the
size of the binary dist created using py2exe from approximately 8MB to ~15MB.

Author: Ryan Haigh
Revision Date: 2008-09-29 13:10:43 UTC

#########################################################################
IMPORT OF EXISTING WORK
#########################################################################
------------------------------------------------------------
revno: 5
committer: Ryan Haigh <haigh.ryan@gmail.com>
branch nick: code_mainline
timestamp: Mon 2008-09-29 22:53:40 +1000
message:
  Moving mainline from local storage to Launchpad project. Due to the fact
  that previous revisions have included image data the current size of the
  branch is too large. The branch history will be abandonned although some
  previous versions of the application will be available in the superseded
  directory.
------------------------------------------------------------
revno: 4
committer: Ryan Haigh <haigh.ryan@gmail.com>
branch nick: code_working
timestamp: Sun 2008-09-07 22:00:43 +1000
message:
  Updated the commenting and docstrings for the various functions and the single
  class. The construct_img function has been heavily modified to incorporate the
  limit paramater which dictates the region within which a imgdatabase image can
  not be re-used, limiting the repetion of images. Setting the limit
  sufficiently high will eliminate repetitions and sufficiently low will allow
  the best possible match with repetitions. These rules may however be broken.
  If all possible matches have been ruled out based on their proximity to
  previous uses, the function will simply use the best match regardless of
  proxmity.

  Additionally the construct_img function now incorporates the ability to
  overlay a copy of the original input image over the constructed mosaic. The
  opacity of this overlay is determined by the overlay argument with 0 being no
  overlay and 1 being full opactiy.

  The pixelize and pixelize_simple functions have had a minor modification where
  if a imgdatabase file matches the tile either better or equally well as the
  last match found it is appended to the list of matches. This changes increases
  the number of possible matches without degrading quality and reduces
  repetition.

  Incorporated a change to the main function to store the matchdata in a file
  on disk so as to limit the time required when debugging other parts of the
  code such as the construct_img function.

  TODO:
  *look at speeding up the matching by using match limits or equality testing
   of the img profile colour lists
  *command line arguments using the optparse module
  *find library of free-to use images to provide better testing
  *add a numeric method to determine how well the mosaic represents the original
   image, perhaps use the overall average of the tiles as a simple benchmark,
   comparing the outpus of simple_avg and the pixelize algorithms.
  *save files to user directory using os.path.expanduser('~')
  *look at alternative profiling/matching such as using greyscale or inverting
   the colours
  *look at using different sized tiles so that some images that match larger
   regions might be used to provide a less uniform appearance
------------------------------------------------------------
revno: 3
committer: Ryan Haigh <haigh.ryan@gmail.com>
branch nick: code_working
timestamp: Thu 2008-09-04 12:25:30 +1000
message:
  Merging changes from code_working into mainline branch, see revision log for
  further details.
    ------------------------------------------------------------
    revno: 2.1.3
    committer: Ryan Haigh <haigh.ryan@gmail.com>
    branch nick: code_working
    timestamp: Thu 2008-09-04 11:32:59 +1000
    message:
      The main() function has been modified to use variables for the variour
      paramaters that will later become arguments supplied via the command line. The
      image database is now stored to a static file and created only when that file
      does not exist. Re-loading the image database from disk when it has been
      created during this run has been fixed.

      Some test code using fprint and fprint2 file handlers stores the order that
      the image profile dictionary tiles are retrieved. A comparison of these files
      after running both matching algorithms indicates that both match the tiles
      in the same order.

      At present the matching functions take the most time and I am looking at ways
      to reduce this, although this may result in a lower overall quality for the
      final mosaic these options will be configurable.

      One example would the the introduction of limits such that the matching
      function finds match within tolerance it stops looking. This has implications
      not only for the quality of the match but also repetitions as there will be
      fewer matches to choose from. Additionally the fact that the order in which
      the imagedatabase dictionary is not random (as per the tileorder test above)
      means that for similar tiles it is far more likely that the same image
      databse file/s will be selected as the match. To address this it may be
      possible to force a more random order which should produce fewer repetitions.

      Another option for speeding up the process of matching would be to first check
      if there are exact matches to the current tile profile in the image database:

       for file,fileprofile in imagedatabase.iteritems():
        if tileprofile.profile == fileprofile.profile:
         matches.append(file)
       if len(matches) > 0:
        print 'ideal match found'
       else:
        normal matching method
    ------------------------------------------------------------
    revno: 2.1.2
    committer: Ryan Haigh <haigh.ryan@gmail.com>
    branch nick: code_working
    timestamp: Wed 2008-09-03 23:10:35 +1000
    message:
      Implemented external function for the construction of the final mosaic based
      on matchdata from the matching algorithm functions pixelize/pixelize_simple.
      This function also includes very basic blacklisting of images to disallow any
      image repetition throughout the generated mosaic however this is presently
      disabled. While no benchmarking has been performed this method of constructing
      the image in the external function means that the PIL image no longer needs to
      be read from the imgstring every time that a better match is found by the
      matching functions.

      One limitation of using the dictionary storage method is that the information
      for each tile/database image is accessed randomly which can make debugging
      somewhat more difficuly although the results are the same. In order to
      overcome this should it become a further problem a list can be constructed
      during the gerneration of image information which will maintain its sequence
      and can be used as the key to retrieve data from the dictionary. That said
      keeping the current random dictionary implementation will force the creation
      of a more robust repetition prevention system and should produce better
      mosaics as the good matches with less 'patterned' look as the initial good
      matches will not be restricted to the first analysed area (and every area
      'repetition limit' from that area where they can be reused).

      As a check to ensure that functionality had been retained during the migration
      to the class storage and renaming (from pyxelize_3) a larger testimage was
      broken into tiles and reconstructed using the pixelize matching algorithm
      implementation. This functioned perfectly indicating the application produces
      similarly accurate results as the previous implementation.

      Previous implementation prior to contruct_img moved to superseded as _4.

      Todo:
      *Implementation of more complex repetition rules for the placement of images
       in the construct_img function. Store the used filenames in the blacklist
       along with a corresponding list of the tilebox positions at which they
       were used then if that same image is a besst match check if it is within
       the repetition range limit and if so move to next match.
      *Implement means of catching if all matches have been exhausted and BREAK
       the repetition rule using the best match, alternatively for each match
       store the distance to the last occurance when checking if it was within
       the repetition limit and choose the furthest image.
      *Current implementation needs to be cleaned up and the commenting re-checked.
      *Docstrings for all functions have been removed as they did not reflect the
       current status/operation of those functions and will need to be replaced.
      *Implement argument parsing for input and output images as well as other
       settings via optparse
      *Implement existing database detection to prevent wasting time regenerating
       for each run
      *Build larger index of tiles based on external images.
    ------------------------------------------------------------
    revno: 2.1.1
    committer: Ryan Haigh <haigh.ryan@gmail.com>
    branch nick: code_working
    timestamp: Wed 2008-09-03 23:07:45 +1000
    message:
      Modified pyxelize to include the use of the main() function in accordance with
      general python guidelines. This version, prior to the implementation of class
      based image profile information was subsequently moved to _superceded as
      pyxelize_3.py

      Implementation of class to store image profile information:
      The profileImage and imageDatabase functions used identical storage mechanisms
      based on simple lists as well as similar methods for generating the required
      profile information. This resulted in unecessary code repetition and made the
      implementation less readable. In order to address this issue a more generic
      ImgProfile class was created.

      The ImgProfile class takes a PIL image object as
      one of its arguements during initialisation, the profile information is then
      generated by the __init__ function based on the image supplied as well as the
      other arguments provided. The use of this class significantly reduced the
      complexity of the functions used to create the database and profile the input
      image. Additionally the profile information is now accessed in a more readable
      fashion via class instance variables, as an example the colour profile
      information for each image is now available as ImgProfile.profile. This colour
      profile is still a list of the form [avgcolour, subsample,subsample,...].

      Adjustment to python naming conventions:
      As well as the implementation of changes associated with the use of ImgClass a
      number of changes have been made to the naming of variables and function names
      throughout the application so as to better adhere to the python style
      guidelines. All instances where image was used have also been changed to img
      to better differentiate pyxelize functions and variables from the PIL Image
      module.

      TODO:
      *Current implementation needs to be cleaned up and the commenting re-checked.
      *Docstrings for all functions have been removed as they did not reflect the
       current status/operation of those functions and will need to be replaced.
      *Currently the matching functions pixelize and pixelize_simple construnct the
       image by pasting over each tile as they go. In order to make implemeting
       repetition rules easier the construction of the image should be moved to
       an external function which is supplied with a dictionary containing
       matchdata (matchdata = {tilebox:[list of matches to this tile]}
      *Implement blacklisting capability which dissallows any repetition.
------------------------------------------------------------
revno: 2
committer: Ryan Haigh <haigh.ryan@gmail.com>
branch nick: code_working
timestamp: Wed 2008-07-16 12:31:08 +1000
message:
  Merging changes from code_working into code_mainline. See revision log for
  details
    ------------------------------------------------------------
    revno: 1.1.2
    committer: Ryan Haigh <haigh.ryan@gmail.com>
    branch nick: code_working
    timestamp: Wed 2008-07-16 12:24:03 +1000
    message:
      Further modifications to incorporate the sub-tile sampling throughout the
      application. Colour information for each tile is now stored within its own
      list object for both the imageprofile and the imagedatabase.

      The pixeMatch algorithm which only analyses the average colour of the entire
      tile has been renamed to pixelizeMatchSimple and a new matching algorithm
      pixelizeMatch created. This second algorithm uses the sub-tile sampling to
      determine the best match.

      In order to test this new matching algorithm the tiles were created from the
      testimage and stored in the imagedatabase. The tiles were created using the
      createThe simplified pixelize algorithm
      was mostly able to reconstruct the original image with a few noticeable tiles
      being out of place. The new sub-tile sampling pixelize algorithm with a
      samplesize value of 2 (1 full tile sample + 4 sub-tile samples) reconstructed
      the image perfectly.

      Benchmarking was also performed:
      Using the tiles generated from the original image being replaced with a
      samplesize value of 1 (no subsampling):
          pixelizeMatchSimple: 5.9849998951
          pixelizeMatch: 9.70300006866
      With the same tile selection and a samplesize value of 2:
          pixelizeMatchSimple: 5.92199993134
          pixelizeMatch: 26.8440001011
    ------------------------------------------------------------
    revno: 1.1.1
    committer: Ryan Haigh <haigh.ryan@gmail.com>
    branch nick: code_working
    timestamp: Tue 2008-07-15 18:14:24 +1000
    message:
      Currently implementation has been modified to include sub-tile sampling for
      the imageDatabase and profileImage functions as well as required modifications
      to other functions to accomodate these changes. The new arguement samplesize
      for these functions determines the number of samples (samples = samplesize*
      samplesize).

      The two pixmatch algorithms have been combined into a single function with a
      new bias arguement which determines the division factor for the dominant
      colour. This function still uses the single average colour to determine the
      best match for the original tile.

      The dumbmatch and histogram based match have been removed but may be found
      in pyxelize_2 in the superseded directory.

      The code has also been more comprehensively documented.
------------------------------------------------------------
revno: 1
committer: Ryan Haigh <haigh.ryan@gmail.com>
branch nick: code_working
timestamp: Sun 2008-07-13 20:20:41 +1000
message:
  Initial import of existing work.

  Currently the application is limited to a single script which creates a
  database of images from a statically defined path. If the database already
  exists it is not recreated.

  Three matching algorithms are implementsd based on the original pixelize
  method. At this stage there is no pattern matching and image tiles are
  characterised by their average colour.

  There is also an additional image manipulation function which replaces the
  tile area with a generated tile with that exact colour.

Author: Ryan Haigh
Revision Date: 2008-03-23 04:06:31 UTC

Merging changes from code_working into code_mainline, see revision log for
details.