Inconsistency in (row, col) and (col, row) conventions

[yuyu2172]

There is inconsistency on conventions used for arguments and return data order of transforms. The conventions refer to (row, col) and (col, row) orders. For example, when a transform takes argument flip_x, flip_y in this order, it is following (col, row) convention.

The issue is that there are functions that follow those conventions, whereas the image shapes follow (row, col) convention.

Currently, the following codes are related to this issue.

• flip related (x_flip, y_flip)
• expand related (x_offset, y_offset)
• crop related (x_slice, y_slice)
• shapes used as argument for transforms such as resize. (shape=(H, W))

[yuyu2172]

For return values, packing all of them into a dictionary may be good. For example, random_flip returns img, params, where params is a dictionary whose keys are x_flip and y_flip.

This is good for three reasons.

• There is no ambiguity in the order of variables. On contrary, tuple of variables does (e.g. params['x_flip'] is self-explanatory).
• Length of parameters are constantly one. This was not the case with tuples: three for random_flip and five for random_expand. This is good because users do not have to remember the number of parameters.
• All intermediate parameters can be called as "params". Therefore, the argument to control whether to return the params or not can be fixed to return_params. This solves issue #83.

[yuyu2172]

@Hakuyume The code your PRed will be changed with the proposal above. What do you think about it?

[yuyu2172]

For arguments, following functions are related

• image/random_flip, image/flip
• bbox/translate_bbox
• bbox/flip_bbox

Although there is an inconsistency, using x_*, y_* in this order for arguments is fine. The reasons behind this are

• Variables starting with name x and y are usually in x,y order because of the order of alphabets.
• When they are taken as arguments, there is less likelihood that users mistake order compared to order of return values, which is the initial concern I had when I raised this issue.

The other alternatives would be to make everything consistent. However, I found them to be less convincing.

The first alternative would be to make everything follow y, x order. However, this would bring up the question of whether to keep order of elements in bounding boxes and keypoints which are currently in x, y order. In scikit-image, everything including bounding boxes are in y, x order. I think that using y, x for bounding boxes and keypoints are very rare conventions.

The second alternative would be to make everything follow x, y order. This means that image shapes will be represented as W, H instead of H, W. I find it increasingly popular to use H, W in many machine learning communities (e.g. TensorFlow), and I think this convention is more natural especially when working with tensors of shape CHW.

[Hakuyume]

I agree with you that inconsistency of the order of axis is a problem. I like (col, row) order, because

• For bboxes and keypoints, x, y order is natural.
• OpenCV uses x, y order for its APIs even though it stores images in (row, col) order.
  • For example, cv2.resize takes (width, height) as the shape of image

[yuyu2172]

After some discussion internally, I agree that making everything in col, row order seems to be best.

We need to change resize related functions.