Channel selectors

[celoyd]

@virginiayung and I want a syntax and mechanism for rio color to apply given operations only to selected channels. For comparison, ImageMagick’s convert works like this:

convert input.tif -channel G -gamma 1.5 -channel B -gamma 0.5 -sigmoidal-contrast 3,50% -channel RGB output.tif

Which is something like this in pseudocode:

G = gamma(G, 1.5);
B = gamma(B, 0.5);
B = sigmoid(B, 3, 50);
write([R, G, B], output.tif);

Implicitly, R is passed through. It amounts to a simple system for creating blocks of operations.

I don’t love the convert syntax (for example, it’s easy to forget to switch back to RGB at the end) but it seems to mostly work. I wonder about something maybe more like this:

rio color 'G(gamma 1.6) B(gamma 0.5, sigmoid 3 50)' input.tif output.tif

Or maybe full s-expressions, or…?

[perrygeo]

We should avoid writing a custom DSL if possible. I think we can do a lot with standard options

# apply to blue and green
--gamma B,G 1.5

# apply to single bands
--gamma G 1.5 --gamma B 0.5

full s-expressions

If the constructs become complex enough to warrant a DSL, s-expressions +1. But let's shoot for standard command line options first.

Related question, are we planning on exposing raw gamma and sigmoidal functions at the command line? The current interface is built entirely around the atmospheric correction function and doesn't expose the lower-level functions. Are we planning on adding those? Replacing the atmoshperic correction with low level constructs? Separate subcommand? Let's talk through the interface...

[celoyd]

👍 I like that optional channel parameter style, @perrygeo.

are we planning on exposing raw gamma and sigmoidal functions at the command line

Yes (is what I’ve been assuming). In fact, I think the simple atmospheric correction may be more high-level than what we want to expose by version 1.0. Maybe it belongs as a wrapper function outside rio color.

I think it makes sense to pitch rio color at about the abstraction level of convert, which I’d sketch as:

• generally more abstract than typing your own arithmetic functions, but
• generally less abstract than functions/tasks which are inexact or have multiple different but valid definitions (like atmospheric correction or removing noise).

Rationale: Arithmetic functions aren’t at the conceptual level of color, and you might as well do them on raw numpy arrays. Conversely, for something as messy as atmospheric correction (for non-satellite readers: e.g., e.g.), rio color shouldn’t try to provide anything that isn’t at least clearly an implementation of a standard technique.

So on reflection (heh), I think it was unwise of me to put simple_atmo in the main path. It probably belongs somewhere to the side as an example or recipe.

I’d defer to a stronger vision – this is just what I have in mind today.

[perrygeo]

@celoyd What about repurposing the rio color command to do the convert-like operations then expose the current functionality as a rio atmo command?

Another wrinkle is that we developed the landsat training set based on the a, b, c parameters for atmospheric correction. If we are shifting gears on rio color, we may need to change our approach to the training data as well.

[perrygeo]

@celoyd what about order of operations? My understanding is that imagemagick performs them from left to right.

In our pxm-sources it looks like we always apply the gamma before sigmoidal contrast. Can we assume that we'll always do gamma correction first in rio color?

[perrygeo]

Also, the modulate command is prevalent in pxm-sources but it's not yet implemented in rio color.

Do we need to add modulate in additional to gamma and sigmoidal contrast?

[celoyd]

Can we assume that we'll always do gamma correction first in rio color?

No. I’ve tried to do that as a convention in pxm-sources, but different order would be important for other applications. I definitely favor left-to-right.

[perrygeo]

Hrm, so click treats options (--blah or -b) as unordered - there is no difference between -b 1 -a 2 -b 3 and -a 2 -b 1 -b 3.

We could

• ditch click and roll our own argparse to accept convert syntax
• come up with a different syntax using ordered arguments or a DSL

[perrygeo]

So I'm moving forward with option 2 - which is to accept ordered arguments rather than options. It results in a sort of mini-DSL that requires a bit of parsing and validation but will ultimately be much more flexible.

Here's the working idea:

$ rio color --help
Usage: rio color [OPTIONS] SRC_PATH DST_PATH [OPERATIONS]...

  Color correction

  Operations will be applied to the src image in the specified order. Each
  operation should be a single quoted argument.

  Available OPERATIONS include:

      "gamma BANDS VALUE"
          Applies a gamma curve, brighten or darken midtones.
          VALUE > 1 brightens the image.

      "sigmoidal BANDS CONTRAST BIAS"
          Adjusts the contrast and brightness of midtones.

      "saturation PERCENTAGE"
          Controls the saturation in HSV color space.
          PERCENTAGE = 0 results in a grayscale image

  BANDS are specified as a comma-separated list of band numbers or letters

      `1,2,3` or `R,G,B` or `r,g,b` are all equivalent

  Example:

      rio color -d uint8 -j 4 input.tif output.tif \
          "gamma 3 0.95" "sigmoidal 1,2,3 35 0.13"


Options:
  -j, --max-procs INTEGER
  -d, --out-dtype [uint8|uint16]
  --help                          Show this message and exit.