NF: Apertures can be defined using image files with transparency

[thomastweets]

Hello again!

When trying to define more complicated apertures to use with (e.g.) ElementArrayStims I ran into frustrations. Here, I added a feature to Aperture allowing to use an image with transparency (I tested with a PNG file) as the basis for the aperture shape.

I tried to change the parameters as little as possible so that I reused the shape parameter. I hope that this does not break anything (I check whether the filename string leads to a real file on disk like in SimpleImage).

One open question would be whether these calls during the _reset need to be disabled again after the draw():

GL.glEnable(GL.GL_ALPHA_TEST)
GL.glAlphaFunc(GL.GL_GREATER,0)

Any comments on that?

Also I hope that was not too bold to include my name in the author list of the file... :)

This is a very slightly modified demo code to test the new feature, including an image with transparency:

#!/usr/bin/env python2

"""Demo for the class psychopy.visual.Aperture().
Draw two gabor circles, one with an irregular aperture and one with no aperture.
"""

from psychopy import visual, event

win = visual.Window([400,400], allowStencil=True, units='norm')
instr = visual.TextStim(win, text="Any key to quit", pos=(0,-.7))
gabor1 = visual.GratingStim(win, mask='circle', sf=4, size=1.2, color=[0.5,-0.5,1])
gabor2 = visual.GratingStim(win, mask='circle', sf=4, size=1.2, color=[-0.5,-0.5,-1])
vertices=[(-0.02, -0.0), (-.8,.2), (0,.6), (.1,0.06), (.8, .3), (.6,-.4)]

# NOTE: size in Aperture refers to the diameter when shape='circle';
# vertices or other shapes are scaled accordingly
aperture = visual.Aperture(win, size=200, shape='wedges.png')  # or try shape='square'

aperture.enabled = False  # enabled by default when created
gabor1.draw()
instr.draw()
aperture.enabled = True  # drawing is now restricted to be within the aperture shape
gabor2.draw()

win.flip()
event.waitKeys()

[peircej]

Looks good. Yes, my hunch is that alpha test should be turned off when the aperture is disabled. But that might need some testing to see what happens (e.g. to normal ImageStims) as a result.

You're doing a good job of maintaining the psychopy structures and names in your dev. Thanks. The perfect thing is if you then add a test for your new feature in the test suite. e.g. you could extend test_aperture in
https://github.com/psychopy/psychopy/blob/master/psychopy/tests/test_all_visual/test_all_stimuli.py
with a line that switches it to use an image aperture and then test that image with a known good one. (I've provided a tool that compares image with example if one exists and creates a new one if not - email if you want more explanation)