"colour.utilities.from_range_.*" definitions mutate their arguments.

[dfoxfranke]

I can't tell from the docs whether this is intended behavior or a bug, but it sure caught me by surprise.

import colour
from colour.utilities import to_domain_100, from_range_100

colour.set_domain_range_scale('1')
x = to_domain_100(1.)
print(x)
print(from_range_100(x))
print(x)
print(from_range_100(x))

Gives:

100.0
1.0
1.0
0.01

I expected:

100.0
1.0
100.0
1.0

to_domain_100 is returning a numpy array, and then from_range_100 is mutating that array in-place.

[KelSolaar]

Hi @dfoxfranke,

Yes, we could explicitly write it in the docs, but from_range is usually used either very close or during the return close thus we don't want to generate an extra copy of the data.

We can surely update the docs to make that clear.

Cheers,

Thomas

[KelSolaar]

Oh and btw, all that system, i.e. the Automatic Colour Conversion Graph, is "beta" and not really production-ready, so thank you for diving into it, you are the first person to really report anything about it!

[dfoxfranke]

Maybe I'm missing an idiom, but I find myself using from_range in a lot of places that aren't adjacent to returns. Suppose I'm writing a function that takes a hue angle h as an argument. I want this function to behave as if it were part of the library, i.e., it should respect scale settings by expecting [0,360] if in Scale-Reference and [0,1] if in Scale-1. So, near the beginning of the function, it executes h = to_domain_degrees(h). But this function calls in to (actual) library functions which also respect scale, so in order to pass them the scale they're expecting, I call them as colour.frobulate(from_range_degrees(h)). You can imagine my surprise when I did this, used h again later in my function, and found that its value had been mutated.

Such code possibly could be simplified by use of Python's with statement to set the scale to a known value within the dynamic scope of the function and restore it to its old value on exit, but the library doesn't seem to provide anything handy for this.

[dfoxfranke]

So I'm picturing an idiom like this:

from colour.utilities import dynscale, to_dyndomain_degrees, from_dynrange_degrees

def frobulate_upsidedown(h):
    with dynscale('1'):
        h = to_dyndomain_degrees(h)
        hp = colour.frobulate(h + 0.5) - 0.5
        return from_dynrange_degrees(hp)

colour.frobulate is a hypothetical function from angle to angle. frobulate_upsidedown is wrapper function which works in a coordinate system that's been transformed 180°. frobulate respects scale and I want upsidedown_frobulate to respect it as well, but I want to be able to work in Scale-1 internally.

The behavior of dynscale(x) on entry is to push the current scale onto a global stack, and then set the scale to x. On exit, it pops the old scale off the stack and sets it back to be the current one again. to_dyndomain_degrees(h) converts from the old scale to the current one, and from_dynrange_degrees(h) converts from the current scale back to the old one.

With something like this available I wouldn't have to write code like in my previous comment, and the mutational behavior of from_range could stay in place and be mimicked by from_dynrange.

[KelSolaar]

Hello @dfoxfranke,

We have context manager in-use in quite a few places internally for exactly the purpose you described (if I understood correctly). It is mentioned here: https://colour.readthedocs.io/en/develop/basics.html#working-with-the-domain-range-scales and the docs (that could use and example): https://colour.readthedocs.io/en/develop/generated/colour.domain_range_scale.html#colour.domain_range_scale

with colour.domain_range_scale('1'):
    colour.adaptation.chromatic_adaptation_CIE1994(XYZ_1, xy_o1, xy_o2, Y_o, E_o1, E_o2)