SphereStim
¶
Attributes¶
|
Class for drawing a UV sphere. |
Details¶
- class psychopy.visual.SphereStim(win, radius=0.5, subdiv=(32, 32), flipFaces=False, pos=(0.0, 0.0, 0.0), ori=(0.0, 0.0, 0.0, 1.0), color=(0.0, 0.0, 0.0), colorSpace='rgb', contrast=1.0, opacity=1.0, useMaterial=None, name='', autoLog=True)[source]¶
Class for drawing a UV sphere. This is a lazy-imported class, therefore import using full path from psychopy.visual.stim3d import SphereStim when inheriting from it.
The resolution of the sphere mesh can be controlled by setting sectors and stacks which controls the number of latitudinal and longitudinal subdivisions, respectively. The radius of the sphere is defined by setting radius expressed in scene units (meters if using a perspective projection).
Calling the draw method will render the sphere to the current buffer. The render target (FBO or back buffer) must have a depth buffer attached to it for the object to be rendered correctly. Shading is used if the current window has light sources defined and lighting is enabled (by setting useLights=True before drawing the stimulus).
Warning
This class is experimental and may result in undefined behavior.
Examples
Creating a red sphere 1.5 meters away from the viewer with radius 0.25:
redSphere = SphereStim(win, pos=(0., 0., -1.5), radius=0.25, color=(1, 0, 0))
- Parameters:
win (~psychopy.visual.Window) – Window this stimulus is associated with. Stimuli cannot be shared across windows unless they share the same context.
radius (float) – Radius of the sphere in scene units.
subdiv (array_like) – Number of latitudinal and longitudinal subdivisions (lat, long) for the sphere mesh. The greater the number, the smoother the sphere will appear.
flipFaces (bool, optional) – If True, normals and face windings will be set to point inward towards the center of the sphere. Texture coordinates will remain the same. Default is False.
pos (array_like) – Position vector [x, y, z] for the origin of the rigid body.
ori (array_like) – Orientation quaternion [x, y, z, w] where x, y, z are imaginary and w is real. If you prefer specifying rotations in axis-angle format, call setOriAxisAngle after initialization.
useMaterial (PhongMaterial, optional) – Material to use. The material can be configured by accessing the material attribute after initialization. If not material is specified, the diffuse and ambient color of the shape will be set by color.
color (array_like) – Diffuse and ambient color of the stimulus if useMaterial is not specified. Values are with respect to colorSpace.
colorSpace (str) – Colorspace of color to use.
contrast (float) – Contrast of the stimulus, value modulates the color.
opacity (float) – Opacity of the stimulus ranging from 0.0 to 1.0. Note that transparent objects look best when rendered from farthest to nearest.
name (str) – Name of this object for logging purposes.
autoLog (bool) – Enable automatic logging on attribute changes.
- property RGB¶
Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb
- Type:
DEPRECATED
- _createVAO(vertices, textureCoords, normals, faces)¶
Create a vertex array object for handling vertex attribute data.
- _getDesiredRGB(rgb, colorSpace, contrast)¶
Convert color to RGB while adding contrast. Requires self.rgb, self.colorSpace and self.contrast
- _selectWindow(win)¶
Switch drawing to the specified window. Calls the window’s _setCurrent() method which handles the switch.
- _updateList()¶
The user shouldn’t need this method since it gets called after every call to .set() Chooses between using and not using shaders each call.
- property anchor¶
- property backColor¶
Alternative way of setting fillColor
- property backColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object.
- property backRGB¶
Legacy property for setting the fill color of a stimulus in RGB, instead use obj._fillColor.rgb
- Type:
DEPRECATED
- property backgroundColor¶
Alternative way of setting fillColor
- property borderColor¶
- property borderColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object
- property borderRGB¶
Legacy property for setting the border color of a stimulus in RGB, instead use obj._borderColor.rgb
- Type:
DEPRECATED
- borderWidth¶
- property color¶
Alternative way of setting foreColor.
- property colorSpace¶
The name of the color space currently being used
Value should be: a string or None
For strings and hex values this is not needed. If None the default colorSpace for the stimulus is used (defined during initialisation).
Please note that changing colorSpace does not change stimulus parameters. Thus you usually want to specify colorSpace before setting the color. Example:
# A light green text stim = visual.TextStim(win, 'Color me!', color=(0, 1, 0), colorSpace='rgb') # An almost-black text stim.colorSpace = 'rgb255' # Make it light green again stim.color = (128, 255, 128)
- property contrast¶
A value that is simply multiplied by the color.
- Value should be: a float between -1 (negative) and 1 (unchanged).
Operations supported.
Set the contrast of the stimulus, i.e. scales how far the stimulus deviates from the middle grey. You can also use the stimulus opacity to control contrast, but that cannot be negative.
Examples:
stim.contrast = 1.0 # unchanged contrast stim.contrast = 0.5 # decrease contrast stim.contrast = 0.0 # uniform, no contrast stim.contrast = -0.5 # slightly inverted stim.contrast = -1.0 # totally inverted
Setting contrast outside range -1 to 1 is permitted, but may produce strange results if color values exceeds the monitor limits.:
stim.contrast = 1.2 # increases contrast stim.contrast = -1.2 # inverts with increased contrast
- draw(win=None)¶
Draw the stimulus.
This should work for stimuli using a single VAO and material. More complex stimuli with multiple materials should override this method to correctly handle that case.
- Parameters:
win (~psychopy.visual.Window) – Window this stimulus is associated with. Stimuli cannot be shared across windows unless they share the same context.
- property fillColor¶
Set the fill color for the shape.
- property fillColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object.
- property fillRGB¶
Legacy property for setting the fill color of a stimulus in RGB, instead use obj._fillColor.rgb
- Type:
DEPRECATED
- property flip¶
1x2 array for flipping vertices along each axis; set as True to flip or False to not flip. If set as a single value, will duplicate across both axes. Accessing the protected attribute (._flip) will give an array of 1s and -1s with which to multiply vertices.
- property flipHoriz¶
- property flipVert¶
- property fontColor¶
Alternative way of setting foreColor.
- property foreColor¶
Foreground color of the stimulus
- Value should be one of:
string: to specify a Colors by name. Any of the standard html/X11 color names <http://www.w3schools.com/html/html_colornames.asp> can be used.
- numerically: (scalar or triplet) for DKL, RGB or
other Color spaces. For these, operations are supported.
When color is specified using numbers, it is interpreted with respect to the stimulus’ current colorSpace. If color is given as a single value (scalar) then this will be applied to all 3 channels.
Examples
For whatever stim you have:
stim.color = 'white' stim.color = 'RoyalBlue' # (the case is actually ignored) stim.color = '#DDA0DD' # DDA0DD is hexadecimal for plum stim.color = [1.0, -1.0, -1.0] # if stim.colorSpace='rgb': # a red color in rgb space stim.color = [0.0, 45.0, 1.0] # if stim.colorSpace='dkl': # DKL space with elev=0, azimuth=45 stim.color = [0, 0, 255] # if stim.colorSpace='rgb255': # a blue stimulus using rgb255 space stim.color = 255 # interpreted as (255, 255, 255) # which is white in rgb255.
Operations work as normal for all numeric colorSpaces (e.g. ‘rgb’, ‘hsv’ and ‘rgb255’) but not for strings, like named and hex. For example, assuming that colorSpace=’rgb’:
stim.color += [1, 1, 1] # increment all guns by 1 value stim.color *= -1 # multiply the color by -1 (which in this # space inverts the contrast) stim.color *= [0.5, 0, 1] # decrease red, remove green, keep blue
You can use setColor if you want to set color and colorSpace in one line. These two are equivalent:
stim.setColor((0, 128, 255), 'rgb255') # ... is equivalent to stim.colorSpace = 'rgb255' stim.color = (0, 128, 255)
- property foreColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object.
- property foreRGB¶
Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb
- Type:
DEPRECATED
- getOri()¶
- getOriAxisAngle(degrees=True)¶
Get the axis and angle of rotation for the 3D stimulus. Converts the orientation defined by the ori quaternion to and axis-angle representation.
- getPos()¶
- getRayIntersectBounds(rayOrig, rayDir)¶
Get the point which a ray intersects the bounding box of this mesh.
- Parameters:
rayOrig (array_like) – Origin of the ray in space [x, y, z].
rayDir (array_like) – Direction vector of the ray [x, y, z], should be normalized.
- Returns:
Coordinate in world space of the intersection and distance in scene units from rayOrig. Returns None if there is no intersection.
- Return type:
- getRayIntersectSphere(rayOrig, rayDir)[source]¶
Get the point which a ray intersects the sphere.
- Parameters:
rayOrig (array_like) – Origin of the ray in space [x, y, z].
rayDir (array_like) – Direction vector of the ray [x, y, z], should be normalized.
- Returns:
Coordinate in world space of the intersection and distance in scene units from rayOrig. Returns None if there is no intersection.
- Return type:
- property height¶
- isVisible()¶
Check if the object is visible to the observer.
Test if a pose’s bounding box or position falls outside of an eye’s view frustum.
Poses can be assigned bounding boxes which enclose any 3D models associated with them. A model is not visible if all the corners of the bounding box fall outside the viewing frustum. Therefore any primitives (i.e. triangles) associated with the pose can be culled during rendering to reduce CPU/GPU workload.
- Returns:
True if the object’s bounding box is visible.
- Return type:
Examples
You can avoid running draw commands if the object is not visible by doing a visibility test first:
if myStim.isVisible(): myStim.draw()
- property lineColor¶
Alternative way of setting borderColor.
- property lineColorSpace¶
Deprecated, please use colorSpace to set color space for the entire object
- property lineRGB¶
Legacy property for setting the border color of a stimulus in RGB, instead use obj._borderColor.rgb
- Type:
DEPRECATED
- lineWidth¶
- property ori¶
Orientation quaternion (X, Y, Z, W).
- property pos¶
Position vector (X, Y, Z).
- setAnchor(value, log=None)¶
- setBackColor(color, colorSpace=None, operation='', log=None)¶
- setBackRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb
- setBackgroundColor(color, colorSpace=None, operation='', log=None)¶
- setBorderColor(color, colorSpace=None, operation='', log=None)¶
Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
- setBorderRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb
- setBorderWidth(newWidth, operation='', log=None)¶
- setColor(color, colorSpace=None, operation='', log=None)¶
- setContrast(newContrast, operation='', log=None)¶
Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message
- setDKL(color, operation='')¶
DEPRECATED since v1.60.05: Please use the color attribute
- setFillColor(color, colorSpace=None, operation='', log=None)¶
Hard setter for fillColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
- setFillRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb
- setFontColor(color, colorSpace=None, operation='', log=None)¶
- setForeColor(color, colorSpace=None, operation='', log=None)¶
Hard setter for foreColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.
- setForeRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb
- setLMS(color, operation='')¶
DEPRECATED since v1.60.05: Please use the color attribute
- setLineColor(color, colorSpace=None, operation='', log=None)¶
- setLineRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb
- setLineWidth(newWidth, operation='', log=None)¶
- setOri(ori)¶
- setOriAxisAngle(axis, angle, degrees=True)¶
Set the orientation of the 3D stimulus using an axis and angle. This sets the quaternion at ori.
- setPos(pos)¶
- setRGB(color, operation='', log=None)¶
DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb
- property size¶
- property thePose¶
The pose of the rigid body. This is a class which has pos and ori attributes.
- units¶
None, ‘norm’, ‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’, or ‘pix’
If None then the current units of the
Window
will be used. See Units for the window and stimuli for explanation of other options.Note that when you change units, you don’t change the stimulus parameters and it is likely to change appearance. Example:
# This stimulus is 20% wide and 50% tall with respect to window stim = visual.PatchStim(win, units='norm', size=(0.2, 0.5) # This stimulus is 0.2 degrees wide and 0.5 degrees tall. stim.units = 'deg'
- updateColors()¶
Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox
- property vertices¶
- property width¶
- property win¶
The
Window
object in which the stimulus will be rendered by default. (required)Example, drawing same stimulus in two different windows and display simultaneously. Assuming that you have two windows and a stimulus (win1, win2 and stim):
stim.win = win1 # stimulus will be drawn in win1 stim.draw() # stimulus is now drawn to win1 stim.win = win2 # stimulus will be drawn in win2 stim.draw() # it is now drawn in win2 win1.flip(waitBlanking=False) # do not wait for next # monitor update win2.flip() # wait for vertical blanking.
Note that this just changes default window for stimulus.
You could also specify window-to-draw-to when drawing:
stim.draw(win1) stim.draw(win2)