ShapeStim

class psychopy.visual.ShapeStim(win, units='', lineWidth=1.5,
    lineColor='white', lineColorSpace='rgb', fillColor=None,
    fillColorSpace='rgb', vertices=((-0.5, 0), (0, 0.5), (0.5, 0)),
    windingRule=None, closeShape=True, pos=(0, 0), size=1, ori=0.0,
    opacity=1.0, contrast=1.0, depth=0, interpolate=True, name=None,
    autoLog=None, autoDraw=False)

頂点の座標(x, y)を並べたシーケンスによって定義される任意の図形を描画するクラスである。

直線、多角形(凸多角形、凹多角形、自己交差を持つもの)、穴があるものや複数の領域からなる図形に対応している。

通常、verticesは頂点(x, y)のシーケンスであり、デフォルトでは閉図形(ポリゴン)として解釈される。折れ線を表すにはcloseShapeにFalseを設定する。closeShapeの値はオブジェクトの作成後は変更できないが、verticesの値はフレーム毎に変更することができる。図形はフレーム毎にori, pos, sizeを用いて回転、平行移動、拡大縮小が可能である。

verticesに頂点(x, y)を並べたループを複数含むシーケンスを指定すると、穴がある図形を定義することができる。輪郭線とcontains()メソッドはこのタイプの図形ではサポートされない。

windingRuleはGLUテッセレータのワインディング規則を制御できる高度なパラメータである(デフォルトの規則はGLU_TESS_WINDING_ODD)。このパラメータは自己交差を持つ図形及び穴を持つ図形にのみ影響する。オブジェクト作成後には変更できない。

Coderデモのshapes.pyを参照のこと。

バージョン1.84.00における変更：複雑な図形塗りつぶしに対応した。この機能はほぼ完全に後方互換性があるが(変更履歴参照)、旧バージョンのShapeStimはpsychopy.visual.BaseShapeStimとして提供されている。

autoDraw

flipの度に自動的に刺激を描画するか否かを指定する。値はTrueかFalseである。一度設定すると再度設定するまで有効なので、flipの度にこの値を設定する必要はない。

autoLog

刺激の設定を変更する度に自動的にログへ出力するか否かを指定する。値はTrueかFalseである。

刺激の位置をフレーム毎に変更する場合のように、頻繁に設定を変更する場合はFalseにするとよい。

closeShape

最後の頂点と最初の頂点を結んで図形を閉じるか否かを指定する。値はTrueまたはFalseである。

ShapeStimの派生クラスであるPolygon, Circle, RectではcloseShapeはTrueと見なされて変更することはできない。

color

刺激の色を指定する。値は以下のいずれかである。

• 色名を合わらず文字列。 standard html/X11 color names ( http://www.w3schools.com/html/html_colornames.asp ) の色名を使うことが出来る。
• 16進数表現。 #aaffe5 など。
• DKL、RGBなどの色空間上でのスカラーまたは3次元の数値。この場合は+=, -=などの複合的な演算代入子に対応している。

色が数値で指定された場合は、刺激の現在の色空間に基づいて解釈される。 値がスカラーで与えられた場合は、3次元全て同じ値を指定したものとみなされる。以下に例を示す。

# 色名による指定
stim.color = 'white
stim.color = 'RoyalBlue'

# 16進数による指定 大文字小文字は区別されない
stim.color = '#DDA0DD' # DDA0DDはプラムの16進数表現

# RGB色空間で赤
stim.color = [1.0, -1.0, -1.0]

# DKL色空間でelev=0, azimuth=45
stim.color = [0.0, 45.0, 1.0]

# RGB255色空間で青
stim.color = [0, 0, 255]

# (255,255,255)と解釈される RGB255色空間では白である
stim.color = 255

# 演算代入子の使用例 すべての成分に1加える。
stim.color += [1, 1, 1]
# -1を乗ずる。色空間上で色を反転する
stim.color *= -1
# RGB255色空間で赤成分を減じ、緑成分を除いて青成分を保つ
stim.color *= [0.5, 0, 1]

setColor()を用いると色と色空間を1つの文で変更できる。以下の二つは同一の処理である。

# その1 setColorを用いて1文で変更
stim.setColor((0, 128, 255), 'rgb255')

# その2 色空間と色をそれぞれ変更
stim.colorSpace = 'rgb255'
stim.color = (0, 128, 255)

colorSpace

使用する色空間を指定する。値は色空間を表す文字列かNoneである。

色を色名や16進数で指定する場合は色空間は設定不要である。Noneが指定された場合はPsychoPyの設定に従う。

色空間を変更しただけでは色のパラメータは変化しないため、画面に表示される色は変化する。表示される色を保ったまま色空間を変化させるには色空間変更後に色も変更する必要がある。以下に例を挙げる。

# RGB色空間でライトグリーンを設定
stim = visual.TextStim(win, 'Color me!',
    color=(0, 1, 0), colorSpace='rgb')

# 色空間をRGB255に変更すると、ほぼ黒色になってしまう
stim.colorSpace = 'rgb255'

# RGB255色空間でライトグリーンにする
stim.color = (128, 255, 128)

contains(x, y=None, units=None)

座標値が刺激の内部であればTrueを返す。 座標値は様々な方法で指定することが出来る。

• X座標とY座標を表す2つの数値を別々の引数として渡す。
• X座標とY座標をひとつにまとめたシーケンスを渡す。
• X座標とY座標を返すgetPos()メソッドを持つオブジェクト(マウスなど)を引数として渡す。

刺激オブジェクトのデータ属性borderを持つ場合はborder、持たない場合はデータ属性verticesの内部に座標値が含まれればTrueを返す。凹があったり輪郭と交差したりしているような複雑な図形でも扱うことが出来る。

刺激にマスク(Gaussianなど)を適用している場合、マスクはこのメソッドで考慮されない点に注意する事。刺激の範囲は純粋にデータ属性size、pos、ori (ShapeStim系のオブジェクトではverticesも)によって定義される。

参照：CoderのshapeContains.pyデモ

contrast

色を決定する際にcolorの値に乗じられる。値は浮動小数点数で-1.0から1.0である。+=, -=などの複合的な演算代入子に対応している。

これによって刺激のコントラストを調節することが出来る。背景が灰色の場合はopacityを変更することによってもコントラストを調節することが可能だが、opacityを使う方法では負のコントラストを設定することは出来ない。以下に例を示す。

stim.contrast =  1.0  # 変化なし
stim.contrast =  0.5  # コントラスト低下
stim.contrast =  0.0  # 一様な灰色
stim.contrast = -0.5  # コントラストが反転して低め
stim.contrast = -1.0  # コントラストが完全に反転

この値を-1.0以下または1.0以上にすることも可能だが、colorの値と乗算した結果色空間の値域を超えてしまった場合は正常に描画されない。

stim.contrast =  1.2  # コントラスト増加
stim.contrast = -1.2  # コントラストを反転させて増加

depth

このデータ属性は廃止された。刺激の重ね順は描画の順番で指定する。

draw(win=None, keepMatrix=False)

刺激を描画する。

引数winが指定された場合はそのウィンドウに描画する。

fillColor

図形の塗りつぶし色を指定する。

(訳注：原文には凹がある図形は正常に塗りつぶせないという注があるが、この問題は1.84.00で解消された)

fillColorSpace

塗りつぶし色の色空間を指定する。

interpolate

刺激のテクスチャを拡大縮小する時に補間を行うか否かを指定する。Falseを指定すると最近傍のピクセルの色が用いられる。Trueの場合は補間がおこなわれる。

lineColor

輪郭線の色を指定する。

lineColorSpace

輪郭線の色の色空間を指定する。

lineWidth

整数または浮動小数点数で輪郭線の太さを指定する。単位はpixである。+=, -=などの複合的な演算代入子に対応している。

name

この刺激オブジェクトに関するログを出力す時の名前を設定する。デフォルト値はNoneである。実験で複数の刺激を使用する際にログファイルの可読性を高める。

名前がNoneの場合は”unnamed <type>”という名前でログに出力される。<type>にはクラス名が入る。例えばpsychopy.visual.TextStimならば”unnamed TextStim”と出力される。

opacity

刺激の不透明度を設定する。値は0.0から1.0で0.0が完全な透明、1.0が完全な不透明である。+=, -=などの複合的な演算代入子に対応している。

透過処理の方法はWindowオブジェクトのBlendModeによって決定される。

ori

刺激の回転角度を設定する。単位は度である。+=, -=などの複合的な演算代入子に対応している。

0度をアナログ時計の文字盤の12時の方向として、正の値が時計回りの回転である。0度未満および360度より大きい値は(370度→10度のように)丸められる。

overlaps(polygon)

個の刺激が他の刺激と交差していればTrueを返す。

交差している対象がポリゴンであれば、その頂点の座標が判定に用いられる。一般的に交差の判定はうまくいくが、非常に尖った図形が剣を交差させたような配置では失敗することがある。

刺激にマスク(Gaussianなど)を適用している場合、マスクはこのメソッドで考慮されない点に注意する事。刺激の範囲は純粋にデータ属性size、pos、ori (ShapeStim系のオブジェクトではverticesも)によって定義される。

参照：CoderのshapeContains.pyデモ

pos

刺激の中心の座標を指定する。座標値の単位はunitsに従う。+=, -=などの複合的な演算代入子に対応している。以下に例を示す。

stim.pos = (0.5, 0)  # 中央やや右寄りに配置
stim.pos += (0.5, -1)  # 刺激をやや右下に動かす
    # これによって(0.5, 0)から(1.0, -1.0)に移動する。
stim.pos *= 0.2  # 座標値に0.2を乗ずる。
    # これによって(1.0, -1.0)から(0.2, -0.2)に移動する。

unitsがpix以外の時にpix単位の位置表現が必要な場合は以下のようにするとよい。

from psychopy.tools.monitorunittools import posToPix

posPix = posToPix(stim)

setAutoDraw(value, log=None)

autoDrawを設定する。

stim.autoDraw = valueと同一である。ログに出力したくない場合はこちらを用いると良い。

setAutoLog(value=True, log=None)

stim.autoLog = valueと同一である。ログに出力したくない場合はこちらを用いると良い。

setColor(color, colorSpace=None, operation=’‘)

ShapeStimとその派生クラスではsetLineColor()とsetFillColor()を用いること。

setContrast(newContrast, operation=’‘, log=None)

stim.contrast = newContrastと同一である。ログに出力したくない場合はこちらを用いると良い。

setDKL(newDKL, operation=’‘)

バージョン1.60.05にて廃止。colorを使用すること。

setDepth(newDepth, operation=’‘, log=None)

このメソッドは廃止された。現在のバージョンでは刺激の重ね順はdraw()の順番で制御される。

setFillColor(color, colorSpace=None, operation=’‘, log=None)

stim.fillColor = colorと同一である。ログに出力したくない場合や色空間を同時に指定したい場合はこちらを用いると良い。

setFillRGB(value, operation=’‘)

バージョン1.60.05にて廃止。fillColorを使用すること。

setLMS(newLMS, operation=’‘)

バージョン1.60.05にて廃止。colorを使用すること。

setLineColor(color, colorSpace=None, operation=’‘, log=None)

stim.lineColor = colorと同一である。ログに出力したくない場合はこちらを用いると良い。

setLineRGB(value, operation=’‘)

バージョン1.60.05にて廃止。fillColorを使用すること。

setLineWidth(value, operation=’‘, log=None)

stim.lineWidth = valueと同一である。ログに出力したくない場合はこちらを用いると良い。

setOpacity(newOpacity, operation=’‘, log=None)

stim.opacity = newOpacityと同一である。ログに出力したくない場合はこちらを用いると良い。

setOri(newOri, operation=’‘, log=None)

stim.ori = newOriと同一である。ログに出力したくない場合はこちらを用いると良い。

setPos(newPos, operation=’‘, log=None)

stim.pos = newPosと同一である。ログに出力したくない場合はこちらを用いると良い。

setRGB(newRGB, operation=’‘, log=None)

バージョン1.60.05にて廃止。colorを使用すること。

setSize(value, operation=’‘, log=None)

stim.size = newSizeと同一である。ログに出力したくない場合はこちらを用いると良い。

setUseShaders(value=True, log=None)

stim.useShaders = valueと同一である。ログに出力したくない場合はこちらを用いると良い。

setVertices(value=None, operation=’‘, log=None)

stim.vertices = valueと同一である。ログに出力したくない場合はこちらを用いると良い。

size

Int/Float or x,y-pair. Sets the size of the shape. Size is independent of the units of shape and will simply scale the shape’s vertices by the factor given. Use a tuple or list of two values to scale asymmetrically.

Operations supported.

units

刺激のサイズ、位置などを指定する際の単位を設定する。None, ‘norm’, ‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’, ‘pix’のいずれかである。 Noneが指定された場合は、刺激を描画するウィンドウの設定に従う。

刺激のunitsを変化してもposやsizeなどの値は自動的に変化しないので、描画結果が変化する点に注意。以下に例を示す。

# この刺激はウィンドウ中心から枠までの幅の20%、高さの50%の大きさである。
stim = visual.PatchStim(win, units='norm', size=(0.2, 0.5)

# 単位をdegに変更すると、幅が視角0.2度、高さが0.5度になる。
stim.units = 'deg'

useShaders

刺激のレンダリングにシェーダーを使用するか否かを指定する。Trueならば使用する。

もし使用しているPCがOpenGL シェーディング言語をサポートしているのならば、この値をTrueのままにしておくことを強く推奨する。シェーダーを使用しない/出来ない場合は刺激の色やコントラストの変更などの操作が遅くなる。

vertices

頂点のX, Y座標を格納したシーケンスのシーケンス、またはNumPyのNx2のarrayオブジェクトを指定する。頂点数が多い場合、頂点の設定に時間を要する。

Operations supported with .setVertices().

verticesPix

刺激の各頂点の現在の座標値をsize、ori、pos、unitsに基づいてピクセルに計算した結果を保持している。

win

この刺激が描画されるWindowオブジェクトを指定する。この引数は省略できない。

例として、同一の刺激を複数のウィンドウに同時に描画するコードを挙げる。二つのウィンドウに対応するWindowオブジェクトが変数win1、win2に格納されていて、刺激オブジェクトが変数stimに格納されているとする。

stim.win = win1  # stimの描画先をwin1に設定
stim.draw()  # win1に描画
stim.win = win2  # stimの描画先をwin2に設定
stim.draw()  # win2に描画
win1.flip(waitBlanking=False)  # win1をflip
             # 垂直同期を待たないのがポイント
win2.flip()  # win2をflip 今度は垂直同期を待つ

このデータ属性はデフォルトで描画するウィンドウを指定するものである。draw()メソッドの引数にWindowオブジェクトを指定することによって、描画時に描画先を指定することが出来る。

stim.draw(win1)
stim.draw(win2)