Gamera 3.x Roadmap

Fortunately, things are in much better shape now than they were for the Gamera 1.x - 2.x transition, which was essentially a rewrite. In most cases, new features can continue to be added to Gamera in an incremental fashion without major changes to the core. However, there are some areas where in order for things to move forward will require some backward-incompatibile changes. This document is a first draft of those changes.

Development method

Since these changes will be backward incompatible, the following will hopefully ease the pain somewhat.

• Use a new major version number (3), to indicate the incompatibility.
• Develop these features on a separate branch of CVS, so bugfixes and small new features can continue to be added to the 2.x series in the CVS head.
• Try our best to have a formal release cycle this time (this has always been difficult for us in the past).
• Create a "Migrating from Gamera 2.x - 3.x" document outlining every change that would be required in third party code to move from Gamera 2.x to 3.x.
• Gamera 3.x will be installed in site-packages/gamera3, and will be imported using "from gamera3...". This way both versions can coexist on the same machine, and users can switch from one system to the other incrementally.

The changes

Move to wxPython 2.6.x

• Benefit: Native Aqua support on OS-X (no more X11 required). GTK2 support (anti-aliased fonts, Unicode). 2.4.x is getting quite old and is no longer maintained, so it may break on certain platforms in the future.
• Pain: All users will have to install the new version of wxPython (not a big deal). Any code using wxPython directly (not through one of Gamera's abstractions, such as the argument GUI) will potentially have to be modified to support the new 2.6.x API. These changes should be minor. Every effort will be made to ensure that Gamera continues to work with wxPython 2.4.2, so in some ways, this is not a backward-incompatible change.

Move to (x, y) coordinates everywhere

This is a controversial one. The argument order when specifying coordinates was debated when Gamera began. However, given all the user feedback and my own experience with trying to use it to integrate third party code into Gamera, I now feel it was a mistake. All functions that take two arguments representing a coordinate or size will be changed to (x, y), and never (y, x) or (row, column).

(FYI: The distinction between nrows and height (and ncols and width) will remain. A single-pixel image will have nrows == 1 and height == 0, since in different situations, one or the other may be more convenient.)

• Benefit: Should be easier to remember the order of arguments. Gamera will be consitent with the majority of other image processing libraries and publications.
• Pain: This will hurt more than a thousand paper cuts dipped in vinegar. Every function that requires coordinates or sizes will need to be changed -- which will surely involve every single Gamera app ever written. The "Migration" document should help, and the use of refactoring tools (such as Bicycle Repairman), may be possible. The bugs created by missing any of these changes will probably be hard to diagnose.

The real question here is "does the benefit outweigh the pain?" I think it does, but feedback on the mailing list is much appreciated.

One possibility to help with this would be to create a "change warning" flag to the 2.x version of Gamera, which, when true, would output warnings from every changed function that its argument order will be changed in 3.x. Assuming full code coverage, that would provide a list of files and line numbers that will need to be changed.

Use signed integers for Point, Size and Dimension objects [CANCELED]

It has been decided this is a bad idea. These types are too relied upon as they are at the low level. Instead, as suggested by Alex Cobb, a new floating-point Point type will be added with easy coercing to/from these integral types. This change should (hopefully) not introduce any backward incompatibilities. Anyway, the original justificaton is below.

• Benefit: Allows for cleaner mathematical operations on Point and Rect objects. Opens the way to a nice Vector toolkit for handling vector paths.
• Pain: Should be transparent on the Python side (unless your images are more than 2^31 pixels wide, in which case you have much bigger problems). May introduce subtle bugs in C++, particularly loops that count backward, but also in other unexpected ways. The experience with adapting the Gamera core will be documented in the "Migration" chapter to help identify trouble areas.

Combine some related plugin methods into a single method

There are certain groups of functions, such as the group "most_frequent_black_vertical_run, most_frequent_white_vertical_run, most_frequent_black_horizontal_run, and most_frequent_white_horizontal_run", that are essentially parameterized by their names. This worked okay when there were only a few of these, but it doesn't really scale (just see the runlength plugin module). I propose combining these into a single function such as most_frequent_run(color, direction).

• Benefit: Less polluted namespace. Easier to see the similiarities between the functions. Easier to manage documentation.
• Pain: All calls to these functions will have to be changed. (Again, documented in the "Migration" chapter).

Officially support Python 2.4, while continuing to support 2.3 (and probably 2.2 on Linux)

This point is here just to make explicit that Python 2.4 will be supported, but not required, by Gamera 3.x. If all goes well, Python 2.3 support will continue. While using decorator systax from 2.4 may be a nice way to specify PluginMethods, I don't think the benefit is so great as to throw out the existing system.

• Benefit: Python 2.4 is faster, and eventually will become the standard.
• Pain: Hopefully none.

Your comments are welcome. Please send them to the gamera-devel mailing list.