[Bf-python] Re: wishes about colorbands

[alex mole]

Hi Nicolas

[I CC'd this to bf-python, as people there may want to join in the 
discussion]

Question for Blender-python coders:
One thing that has occurred to me about implementing this sort of thing, 
is that within Blender, colorbands are not reference counted or managed 
anywhere centrally. How can you prevent dangling pointers with the 
python objects? Is there an accepted way of doing this?
Also, should assigning None to a texture's colorband attribute delete 
the object within Blender?


My responses to your mail follow....


nicolas bonnand wrote:
> Hi,
> 
> If I could make a wish...
> 
> I'd like colorband to be a class
> by itself.

I agree. It'll probably be a class called Blender.Texture.ColorBand

> 
> I'd like to manipulate colorbands
> instances as objects, and even
> as "named" objects.
 > I could have a rainbow colorband called "rainbow",
 > , etc ...
 > and I could ask "Give me the colorband object whose
 > name is 'rainbow' "

I'm not sure I like this idea. IMO, the python interface to Blender 
should be a fairly transparent wrapper around the objects that actually 
exist inside it. As Blender does not associate names with colorbands, I 
don't think that the python interface should. It would require some 
pretty ugly hacks to make it work, and I don't like ugly hacks :)

Of course, depending on how you're using them, you could replicate 
something similar yourself using Blender.Registry, as long as all of 
your colorbands are created from python...

> A colorband class would facilitate works with colorbands
> (colorbands import and export with other applications
> such as The Gimp for example.)

Again, I'd rather leave such things to the user. It would be pretty 
trivial to implement loading and saving CB data entirely withing python, 
so I don't think that the actual C code should touch it.

> The idea would be somethings like this:
> (the following is not python code,
> it is rather imaginary code)
> 
> 
> ###### class ColorBandPoint #######
> 
> attributes:
> -----------
> r: red value from 0.000 to 1.000
> 
> g: green...
> 
> b: blue....
> 
> a: alpha...
> 
> 
> methods:
> -------
> new()   constructor
> 

The struct within Blender is called "CBData", but 
Blender.Texture.ColorBandPoint is probably a better name for it :)
I'd also like to have the position in here.
[I don't think that the C struct's "cur" value needs to be included 
though, but I'm not certain what it does ;)]


> ###### class ColorBand #####
> 
> attributes:
> -----------
> data:   { hash of ColorBandPoint objects, the hash keys being the 
> ColorBandPoint positions}

I think that a list would be better than a dictionary, basically because 
floating point values are notoriously unstable, and there may be issues 
with this [possibly not though... does anyone have a strong opinion one 
way or the other?]. I like the idea in principle though...

> name:   the name of the color band

As I mentioned before, I think that names would be a Bad Thing.

> interpol: the interpolation type (E, L or S )

The way the rest of the Texture module [and much of the rest of the API] 
works is to split this into two sections: an attribute which is just the 
Blender constant [plus an appropriate constant dictionary], and get/set 
functions which deal with strings [eg. 'Linear', 'Spline' and ??? 
whatever E stands for :)]. It would be nice to be consistent about this 
sort of thing, so I guess that interpol will work the same way.

> methods:
> -------
> new()   constructor
> 
> getColorband(optional string name)
> -> returns a colorBand object whose name is name
> -> returns the complete list of colorbands defined
> in the scene, if name is not given

I don't think that this function should be here. Blender ColorBands 
aren't stored anywhere globally- they are just owned by textures. To 
reflect this, colorband classes should only be "gettable" from 
individual Blender.Texture.Texture objects. It will be possible to 
create new ColorBand objects and set them to Texture objects, and it 
will be possible to assign None to a Texture's colorband, which will 
effectively delete the object [and update internal flags to turn CB off].

> addPoint(ColorBandPoint cbp,float pos)
> -> insert the colorbandpoint cbp in the colorband
> at the position pos
> 
> delPoint(float position)
> -> delete a point in the colorband

I'm happy with these, except that I think that "position" should be 
encapsulated within ColorBandPoint. Of course, they might not be 
necessary, as ColorBand.data.append() will do the same as addPoint, and 
.remove(x) or .pop(i) would do the same as delPoint(). ColorBand.data 
should also be happy with being assigned to from arbitrary sequences of 
ColorBandPoint objects.

> delColorBand()
> -> delete the colorband

This isn't really necessary. Python's garbage collection will do this 
automatically when all the references have been forgotten.

>

> ### and for the existing Class Texture ####
> 
> 
> new attributes:
> ---------------
> colorband: the colorband object linked with the texture

Yes, makes sense :)

> new methods:
> ------------
> setColorBand(ColorBand cbd)
> -> link texture instance with colorband
>
> unsetColorBand()
> -> delete link between colorband from texture
>  but don't delete colorband object of course !

I'm happy with these, but I think that "unset" should be "clear", to 
keep a bit more in-style with the rest of the API :)

> registerColorBand(string name)
>  Suppose someone, creates a colorband, not
> from python, but directly from blender user
> interface.Python might not be aware of it.
> This function, would be used to tell python:
> " Hey ! There's a colorband in this texture !
> Python, could you please create a colorband
> object that matches it "

Again, IMHO this sort of thing should be implemented entirely within python.



Thanks for your input- it's really nice to have somebody else on board :)


Alex