feature.greycomatrix angles clockwise or counterclockwise?

[sdtaylor]

Description

When I use the grey co-occurrence matrix with a vertical angle, I expected 90° (pi/2 radians) to refer to the pixel above the reference pixel, thus be a counterclockwise direction. But the code below implies it's a clockwise direction. The docs don't specify this, so is the clockwise direction correct?

Way to reproduce

import numpy as np
from skimage.feature.texture import greycomatrix

image = np.array([[2,0,0],
                  [0,0,0],
                  [0,0,0]], dtype=np.uint8)
result = greycomatrix(image, [1], [np.pi/2], levels=4)

result[:,:,0,0]
array([[5, 0, 0, 0],
       [0, 0, 0, 0],
       [1, 0, 0, 0],
       [0, 0, 0, 0]], dtype=uint32)

# Using 270° produces what I expected with 90°
result = greycomatrix(image, [1], [np.pi*1.5], levels=4)
result[:,:,0,0]
array([[5, 0, 1, 0],
       [0, 0, 0, 0],
       [0, 0, 0, 0],
       [0, 0, 0, 0]], dtype=uint32)

Version information

# Paste the output of the following python commands
from __future__ import print_function
import sys; print(sys.version)
import platform; print(platform.platform())
import skimage; print(f'scikit-image version: {skimage.__version__}')
import numpy; print(f'numpy version: {numpy.__version__}')

# your output here
3.8.12 (default, Oct 12 2021, 13:49:34) 
[GCC 7.5.0]
Linux-5.4.0-89-generic-x86_64-with-glibc2.17
scikit-image version: 0.18.3
numpy version: 1.21.3

[jni]

Yeah, I think you're correct @sdtaylor, it's clockwise. You can see the inner loop here:

scikit-image/skimage/feature/_texture.pyx

Lines 53 to 71 in 371964e

	for a_idx in range(angles.shape[0]):
	angle = angles[a_idx]
	for d_idx in range(distances.shape[0]):
	distance = distances[d_idx]
	offset_row = round(sin(angle) * distance)
	offset_col = round(cos(angle) * distance)
	start_row = max(0, -offset_row)
	end_row = min(rows, rows - offset_row)
	start_col = max(0, -offset_col)
	end_col = min(cols, cols - offset_col)
	for r in range(start_row, end_row):
	for c in range(start_col, end_col):
	i = image[r, c]
	# compute the location of the offset pixel
	row = r + offset_row
	col = c + offset_col
	j = image[row, col]
	if 0 <= i < levels and 0 <= j < levels:
	out[i, j, d_idx, a_idx] += 1

The key is:

                offset_row = round(sin(angle) * distance)
                offset_col = round(cos(angle) * distance)

That measures the offset from the central pixel. Since sin and cos both start out positive, at an angle of 0 we start with an offset right, and as we increase the angle we move down, ie clockwise.

imho, for 1.0, we should swap the sin and cos calls. This would align with row/col coordinates and we would end up with a counterclockwise rotation starting from the rows axis (axis 0). Thoughts @scikit-image/core?

@sdtaylor in the meantime, we would certainly welcome a clarification to the docstring!