Doc clarification: BGR expected for HSV custom range

[ajstewart]

Hi! I'm not sure if this is a bug or intended, hence the discussion. I was caught out today when using the threshold.custom_range with an HSV channel as I was not using the pcv.readimage framework to load my image array, instead I already had an RGB image array to pass through.

I was caught out by the function expecting the array to be BGR and not RGB:

plantcv/plantcv/plantcv/threshold/threshold_methods.py

Line 352 in df07ef6

hsv_img = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)

Of course this is the cv2 default so I'm not surprised, I was just wondering if this should be stated on the documentation of the method?

As here: https://plantcv.readthedocs.io/en/stable/custom_range_threshold/ it mentions that the input is RGB image data which could be a bit confusing if like me, you attempt to use the method with an RGB array already obtained.

I see there was a similar previous discussion about this in #559 for the RGB threshold.

Thanks (and thanks for plantcv)!

[nfahlgren]

Hi @ajstewart, PlantCV primarily uses OpenCV, so our default handling of RGB images is BGR. When we use another tools (e.g. scikit-image) we convert between BGR->RGB->BGR in the backend when needed. But you are correct, pcv.threshold.custom_range requires a BGR image.

In the documentation we refer to color images as RGB because that is the terminology most people are familiar with. Since most users use pcv.readimage they are working with BGR images without necessarily realizing they are. Since you loaded an image with another tool (which other users may also do), we should document a procedure for converting images from scikit-image, imageio, etc. into OpenCV/PlantCV compatible images.

We have had team discussions about the BGR/RGB issue, which is problematics because 1) OpenCV is the outlier; and 2) the NumPy arrays are not annotated so you cannot tell the difference between BGR and RGB. Our longer term idea is to customize image NumPy arrays by extending them with some custom properties and/or methods so that you can distinguish between BGR, RGB, grayscale, hyperspectral, etc. and convert between them easily when needed. We have prototyped the basic functionality in #909

[ajstewart]

Hi @nfahlgren, thanks very much for your reply. That's all understandable and what I suspected. It's not the first time and won't be the last time I'm caught by the OpenCV BGR. I will keep this in mind going forward, and really the answer is to keep within the ecosystem as much as possible. Maybe a note somewhere on the docs would help just to remind of the expectancy that it is an 'opencv' style array (there might already be one?).

That longer term solution looks like a good path to go down!