(x, y) coordinate consistency

In Gamera 2.x, some functions received coordinates in the order (y, x), (or (rows, cols)), while others took coordinates in (x, y) order. This self-inconsistency and departure from the majority of image processing systems often resulted in confusion and subtle errors.

The new recommended way to call these functions is to pass in Point, FloatPoint, Size or Dim arguments as required, instead of two integers. This solution allows the old function signatures to be maintained for backward compatibility, while allowing migration to a style that consistently uses (x, y) ordering everywhere.

For example, image.get(r, c) becomes image.get(Point(c, r)).

Functions should be parameterized by arguments, not by name

There are certain groups of plugin functions that perform essentially the same functionality. Take for example:

black_horizontal_run_histogram()
black_vertical_run_histogram()
white_horizontal_run_histogram()
white_vertical_run_histogram()

These four functions compute a run length histogram, parameterized by the color and direction of the runs. Maintaining four separate functions for a single logical task has a number of disadvantages:

• Even if the code is abstracted such that the core of the algorithm is in a single function, the documentation still needs to be updated in multiple places.
• The generated documentation becomes longer and therefore harder to browse through, and contains a lot of redundant information or excessive hyperlinking.
• Autocompletion in the Gamera shell becomes less useful.
• Alphabetization of the functions doesn't necessarily reveal their membership as part of the same family of functionality.

Therefore, in Gamera 3.x, these sorts of functions have been merged into a single function. For example, the four functions above are now the single function:

run_histogram(color, direction)

C++ code

On the C++ side, all deprecated function calls will be caught at compile time. Simply recompiling your C++ code will provide compiler warnings to this effect.

The compiler warnings produced by gcc can be fairly cryptic. The gamera_deprecation_filter (described below) will filter these warning messages and produce detailed human-readable suggestions for updating your deprecated calls.

Python code

Finding the deprecated calls in Python code is somewhat more difficult, since the exact function calls being made cannot be determined until runtime.

When a deprecated function call is made, a deprecation warning is printed to stderr. This message provides the name of the deprecated function, the reason it was deprecated, and a suggested alternative. The only way to find all deprecated calls in your code this is to ensure that all of your code is run. This is sometimes difficult to do, though a code coverage tool such as Garth Rees' Statement coverage for Python may help.

A manual search through your code for deprecated functions may in some cases be more efficient. A master list of all deprecated Python functions in Gamera is presented in the Python deprecations reference.

gamera_deprecation_filter

The gamera_deprecation_filter tool is useful for correcting calls to deprecated Gamera functions from you C++ code.

This tool only works with gcc, and only on non-MS Windows platforms (for some unknown reason.

The output from gcc about deprecated functions is helpful, but is somewhat limited. For example:

include/dimensions.hpp:314: warning: `__comp_ctor' is deprecated
(declared at include/dimensions.hpp:216)

Here __comp_ctor refers to the constructor of the Dimensions class. Not only is this cryptic, but it doesn't specify which of the overloaded signatures it is referring to (except by line numbers). It also doesn't explain why the function call was deprecated or suggest a reasonable alternative.

This filter replaces these cryptic warnings with more human-readable ones by extracting and displaying the comment associated with the deprecated function. For example, the above warning becomes:

include/dimensions.hpp:314: warning: deprecated call
return Dimensions(nrows(), ncols());

Dimensions(nrows, ncols) is deprecated.

Reason: (x, y) coordinate consistency.

Use Dim(ncols, nrows) instead.

This script can be used as a filter or on a given filename. Be sure to send stderr to gamera_deprecation_filter.

Usage as a filter:

$ python setup.py build 2>&1 | ./migration_tools/gamera_deprecation_filter

or offline:

$ python setup.py build &> log
$ ./gamera_deprecation_filter log

replace_get_set

This script searches through C++ source files and corrects all uses of get and set in the deprecated Gamera 2.x style to the new Gamera 3.x style. For example:

get(r, c)

will change to:

get(Point(c, r))

Note that this script uses regular expressions and is pretty naive about its understanding of C++, and will replace any method .get or .set (or ->get and ->set), not just those on Gamera Image objects, so it is recommended to check the results with a visual diffing tool.

Usage on files:

$ ./replace_get_set source.hpp > source.hpp.new

or as a filter:

$ cat source.hpp | ./replace_get_set > source.hpp.new