Region additions

[jeromedecoster]

Hi,

I really enjoy using Sikuli.
But in my daily scripting there is some missing methods I think it can be useful to add.
Currently I monkey patch some python class (Region, ..) but I think it's a good idea to add these functionnalities in a next built-in Sikuli.

I'm not a python/JPython/Java expert, so I don't send you a bad pull request.

For my examples, some Regions and Location

r0 = Region(10, 10, 10, 10)
r1 = Region(15, 15, 2, 10)
l0 = Location(15, 25)

Here just some useful functions:
Region.union(Region)

# return a new region, new bounds includes r0 and r1 (x=10, y=10, w=10, h=15)
r0.union(r1)

Region.union(Location)

# return a new region, new bounds includes r0 and l0 (x=10, y=10, w=10, h=15)
r0.union(l0)

//

Region.intersects(Region)

# return a Boolean to say if r0 intersects r1 (True)
r0.intersects(r1)

//

Region.intersection(Region)

# return a new region, new bounds is the intersection of r0 and r1 (x=15, y=15, w=2, h=5)
r0.intersection(r1)

//

Region.contains(Region)

# return a Boolean to say if r1 is fully included in r0 (False)
r0.contains(r1)

Region.contains(Location)

# return a Boolean to say if r1.topLeft is included in r0 (True)
r0.contains(r1.topLeft)

//

Also right, left, above, below are useful but I think a optional parameter can be added to extends the current Region instead of always exclude it.

r0 = Region(10, 10, 10, 10)
# return a new region (20, 10, 100, 10)
r1 = r0.right(100) 

if I want include r0, I need to r0.union(r1). That makes 2 steps.
A better way is to have an option, setted by default to False to stay with the same behavior than in previous Sikuli versions

Region.right(range, union=False)

# return a new region (10, 10, 110, 10) So useful !
r1 = r0.right(100, True)

//

Also Region supports 1 or 4 arguments
Region(Region)
Region(x, y, w, h)

Perhaps it's a good idea to add this possibility:

# same of Region(Screen()), take the Screen 0 bounds if no argument setted
reg = Region()

What do you think ?

Thanks,
Jerome

[RaiMan]

Thanks for your input.

--- The ideas union, intersection, intersects and contains seem to be useful. I have added a request bug on Sikuli's launchpad, since this is still the right place for requests, answers and bugs.

BTW: Region knows getRect() (sorry, not in the docs ;-), which returns a Java rectangle object, which in turn understands the features you requested and can be used as well on the Python level, e.g.

regUnion = Region(r0.getRect().union(r1.getRect()))

--- right, left, above, below
The idea is ok, but the implementation should be with extra API calls like expandRight().

Currently you can do it this way as a one-liner

r0 = Region(10, 10, 10, 10)
aRange = 100
newReg = r0.left(1).right(r0.w+aRange)

or with the rectangle cast

r0 = Region(10, 10, 10, 10)
aRange = 100
newReg = Region(r0.getRect().union(r0.right(aRange).getRect())

I will add an extra request bug for this.

--- reg = Region()
meaning the whole default screen is not really needed, since you can say:

newReg = SCREEN
# or
newReg = Screen(0)

which would even talk more to people reading the code.

[RaiMan]

added request bugs to Sikuli's launchpad:
--- https://bugs.launchpad.net/sikuli/+bug/905400
--- https://bugs.launchpad.net/sikuli/+bug/905402