Add optional pixel to mm conversion in plantcv.analyze.size and others

[rayn-alex]

Is your feature request related to a problem? Please describe.
I want to convert the pixel size values to mm so it's written in the outputs with the unit mm

Describe the solution you'd like
Add an option to the function that leads to a conversion of the px values to mm or mm². This could simply be a conversion factor. E.g.:
plantcv.analyze.size(img, labeled_mask, n_labels=1, label=None, px_conversion_factor=None)

Describe alternatives you've considered
It's always possible to do the conversion outside plantCV. However, I think it'd be convenient and it might be useful for more users.

If you all think an option like this makes sense, I could implement this in plantcv.analyze.size as well as all the other functions where this might be relevant (please help me to list all).

[HaleySchuhl]

Thank you @rayn-alex for the suggestion, I do think it would be convenient to report the scaled measurements. This is a change that @nfahlgren and Katie have discussed a couple months ago, but decided that this conversion would make most sense happening outside the pcv.analyze.size function for reproducibility.

We revisited the topic this morning and they agreed that we could put it into a new function, maybe something like pcv.analyze.scale_size where the observation value & scale gets overwritten for all size related observation, and the scaling factor would also get saved as a new metadata observation.

[rayn-alex]

Hey @HaleySchuhl, sound reasonable!
I can look into this as well and make a suggestion. Not in the next days but weeks.

[HaleySchuhl]

Found the old issue, so tagging here for ease #926

[nfahlgren]

Rather than a new function, I was thinking we could add new global parameters that are used by analyze functions (in the Params class).

Something like this:

px_per_unit_x = 1
px_per_unit_y = 1
px_units = "pixels"

If the analyze functions scaled the recorded observations with these then the outputs would be in pixels and the values would be unchanged. But if we set these (manually or automatically) by replacing the scaling factors and the units to cm, mm, etc. then the outputs would reflect that new scale and units.

[rayn-alex]

Hm! This would be a neat solution, and probably better than a new function. However, this would require to update all analyze functions, right?

What do you all prefer? I think I'd vote for adding a new global parameter.

[Li-Alvarez]

Hi! I am using PlantCV for multiple trays, and in the output file, I obtain the delimited and calculated area in pixel units. Since I am not using a color card as a reference, how should I convert the output data to cm² or mm²? Or is there a function that simplifies this process? Thanks!

[rayn-alex]

Hey @Li-Alvarez you don't need a color card for this. You have to assess your mm-to-pixel conversion factor at a certain distance. From this, you can calculate the mm-to-pixel conversion factor at any distance because the distance-to-surface ration is constant. Multiply your pixel values with this factor.

We are currently working on implementing functionality in plantCV that does this for you (hence this issue).

E.g.: Take an image of a ruler at 1m distance and calculate how many pixels are one mm (average). Let's say it's 1px = 1mm
Then at 0.5m you would have 1m/0.5m = 2 ⇒ 2x1px = 1mm at this distance.

[HaleySchuhl]

this would require to update all analyze functions, right?

What do you all prefer? I think I'd vote for adding a new global parameter.

Agreed @rayn-alex , the analyze functions including size, bound_horizontal, and bound_vertical will need to utilize the scaling factor. We had a discussion and agree that a global parameter sounds best, but adding them as another Output metadata so that measurements could be back-transformed for reproducibility.

This part I am not suggesting you tackle unless you want to: We can also include the calculation of the px_per_unit scaling factors. Since we use color cards in many cases, this could mean taking the outputs.metadata from detect_color_card like median chip height and width. Part of this math requires the known size of color cards, which we have information about in a google doc here.

Excited to collaborate further with you on this enhancement.

[rayn-alex]

Hey @HaleySchuhl, please excuse my silence on this.

I could dedicate some time to this in the next days and provide a first suggestion.

It would be great to include the calculation of the px_per_unit. Maybe not only with color cards, but also using the distance and a predetermined scaling factor (predetermined from a custom reference, e.g. like in the example I gave to Li-Alvarez above). At least that's what I wanted to implement for the RAYN Vision System camera because we know the distance to px/mm relation.

Do you have an idea how we can avoid a breaking change here? Only scale if the factor is set?

I'm also available for a quick call if that helps to coordinate work on this.

[HaleySchuhl]

That's a great suggestion giving the option of using a custom scaling factor.

Yeah I'm imagining the global parameter px_per_unit would default to 1 similar to how saved_color_scale defaults to None. Meaning we also need to save the new units too which would default to pixels haha. This is a highly involved update so I agree a call to coordinate sounds smart. These don't need to be parameter inputs for the size function, instead it will just be a global parameter.

Just recently during a workshop we were reminded how annoying size scaling is downstream, so this enhancement will be a big help!