API redesign

[danielballan]

Here is an alternative API, using plain Python objects as much as possible.

Update: Revised in next comment

pool = SqlImagePool('path')
# partition is a function that returns a list of Tile objects
tiles = partition(img, dimensions, ...)  # tiles should be analyzed during their init
# more verbose tuning API might make it less mysterious, more customizable
palette = compute_palette(img_historgram(img))
tiles = tune(tiles, palette)  # returns a copy of the tiles
mosaic = match(tiles, pool, ...)
# mosaic is a dictionary mapping each tile object to an image_id from the pool
result_img = assemble(mosaic, tiles, pool, ...)

By putting the tile<->pool_img assignment in a dict instead of in the Tile's state, we can hold more than one mosaic option at once.

[danielballan]

Summarizing ideas from phone conversation:

• partition(source_img, dimensions, ...) returns a list of tuples of slices, e.g.,

  tiles = [(slice(1, 2), slice(10, 20)), (slice(2, 3), slice(10, 20)), ...]

• analyze(source_img, slice_obj, shape=None) returns colors as a 3D numpy array of shape (width, height, 3). The last dimension is CAM02-UCS* color (or whatever color space the user wants...). If the argument shape=None (the default), individual pixels are analyzed. If the user specifies shape=(2, 2), the image is averaged into quadrants and then analyzed, and the resultant array has the shape (2, 2, 3). Turn this into a vector is as simple as:

  colors = [analyze(source_img, t) for t in tiles]
  color_vector = np.concatenate([c.reshape(-1, 3) for c in colors])
  # The -1 is a numpy convention that means,
  # "Make this however long it needs to be to use all the elements."

• match(tiles, colors, pool) returns mosaic, a dict mapping tiles to some id from the pool
• assemble(mosaic, pool, ...) returns the result image, a numpy array

*Here is a well-reserached color conversion utility (incidentally by Nathaniel Smith, a core dev on numpy). It includes CAM02-UCS and other perceptually uniform spaces, as well as spaces that simulate color blindness. https://github.com/njsmith/pycam02ucs

[danielballan]

Some of these ideas -- the good ones ;- ) -- were incorporated in #9.