BufferImageStim¶

class psychopy.visual.BufferImageStim(win, buffer='back',
    rect=(-1, 1, 1, -1), sqPower2=False, stim=(), interpolate=True,
    flipHoriz=False, flipVert=False, mask='None', pos=(0, 0),
    name=None, autoLog=None)

「スクリーンショット」を撮ってImageStimオブジェクト(RGBAモード)として保持する。

スクリーンショットはそれを撮った瞬間に描かれている視覚刺激のコラージュであり、ひとつの刺激オブジェクトして使用できる。スクリーンショットはフロントバッファからでもバックバッファからでも取得できる。

BufferImageStimは高速な刺激のレンダリングを目的としたものであり、回転、平行移動、不透明度を動的に変更できる。(ImageStimのように)描画は高速だが初期化には時間を要する。

スクリーンショットの撮影時には刺激の一部分だけを切り出すことが可能である(単位はnormを用いる)。また、特定の刺激群を刺激オブジェクトを並べたリストとして指定することも出来る。結果として、それらの刺激のみをピクセル化した画像が得られる。グラフィックドライバのOpenGLサポートに任意サイズの画像が含まれていない場合はｍ必要に応じて2の冪の正方形のサイズになるように大きく切り出される。余分な余白部分はアルファチャネルを用いて不可視化される。このクラスの目的はレンダリングされたバッファーの内容を保持しておくことである。

OpenGL 2.1以上をサポートするグラフィック環境を用いるか、2の冪サイズの画像を用いること。以下に使用例を示す。

# 刺激を作成し、リストに格納する。
mySimpleImageStim = visual.TextStim(myWin, image='stim.jpg')
myTextStim = visual.TextStim(myWin)
stimList = [mySimpleImageStim, myTextStim]

# 刺激をレンダリングしてキャプチャする (時間を要する：ログで確認すること)
screenshot = visual.BufferImageStim(myWin, stim=stimList)

# キャプチャした刺激をレンダリング (初回のdrawを除いて非常に高速)
while conditions:
    screenshot.draw()  # 回転、平行移動、不透明度を指定可
    other_stuff.draw() # 動的な刺激は別途描画
    myWin.flip()

初期化時のパラメータは以下のとおりである。

パラメータ	解説
buffer	‘back’ならばバックバッファ、’front’ならばフロントバッファをキャプチャする。
rect	左端のX座標、上端のY座標、右端のX座標、下端のY座標の値を並べた長さ4のシーケンス。キャプチャする範囲を指定する。単位はnormである。デフォルト値は[-1, 1, 1, -1]、すなわち画面全体である。
stim	バックバッファに描画する刺激を並べたリストである。並べた順に描画される。(flip()することなく) バックバッファがまずクリアされ、刺激が描画され、最後にバッファがキャプチャされる。リストに並べる個々の要素はdraw()メソッドを持つオブジェクトで、同じWindowオブジェクトに刺激を描画するように設定されていなければならない。
interpolate	補間を行うか否かを指定する。Trueならば補間される。特にキャプチャした画像を回転して描画する場合はTrueにしておいた方が良好な結果が得られる。
sqPower2	Falseならばrectで指定された大きさでキャプチャを行う。OpenGL 2.1以上をサポートしているグラフィック環境でなければならない。デフォルト値はFalseである。Trueならば2の冪のサイズでキャプチャする。
flipHoriz	Trueなら左右反転してキャプチャする。デフォルト値はFalseである。
fflipVert	Trueなら上下反転してキャプチャする。デフォルト値はFalseである。

autoDraw¶

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

autoLog¶

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

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

刺激に割り当てられたテクスチャを全て消去する。

バージョン1.61.00以降ではこのメソッドはガベージコレクションの時に自動的に呼び出されるので、ユーザーが明示的にこのメソッドを呼び出す必要はなくなった。

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が指定された場合はそのウィンドウに描画する。

flipHoriz¶

Trueを設定すると画像が左右反転する。反転の対象はオリジナルの画像であり、oriなどによる回転を適用した後の画像ではない点に注意。

flipVert¶

Trueを設定すると画像が上下反転する。反転の対象はオリジナルの画像であり、oriなどによる回転を適用した後の画像ではない点に注意。

image¶

描画する画像ファイルを指定する。PILがサポートする形式に対応している。

(訳注：親クラスからドキュメントを継承しているからこの項目があるだけで、これを設定する意味はないと思われる)

interpolate¶

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

mask¶

アルファマスクを設定する。以下の形状のマスクを使用出来る。

————— —————————————————- 値備考 ————— —————————————————- None マスクなし ‘circle’ 円形の窓 ‘gauss’ ガウス関数に従って周辺に向かって透明度を増す窓 ‘raisedCos’ Raised Cosine窓画像ファイル名画像をマスクとして使用する numpyのarray 1xNまたはNxNで値が-1.0から1.0のもの ————— —————————————————-

maskParams¶

マスクのパラメータを指定する。デフォルト値はNoneである。

‘gauss’の場合は、{‘sd’:5}という具合にガウス関数の標準偏差を辞書オブジェクトで指定する。

‘raisedCos’の場合は、{‘fringeWidth’:0.2}という具合にフリンジ幅を指定する。値域は0.0から1.0で、Raised Cosine窓のエッジによってぼかされる範囲が変化する。

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=’‘)¶

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

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

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

setDKL(newDKL, operation=’‘)¶

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

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

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

setFlipHoriz(newVal=True, log=None)¶

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

setFlipVert(newVal=True, log=None)¶

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

setImage(value, log=None)¶

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

setLMS(newLMS, operation=’‘)¶

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

setMask(value, log=None)¶

stim.mask = 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(newSize, operation=’‘, units=None, log=None)¶

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

setUseShaders(value=True, log=None)¶

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

size¶

刺激のサイズ(幅、高さ)を設定する。単位はunitsに従う。

値は幅、高さに設定する値を(x, y)のように並べたシーケンスか、2.0のようなスカラー値(幅、高さともこの値に設定される)か、None(デフォルト値にリセット)のいずれかである。 +=, -=などの複合的な演算代入子に対応している。

幅や高さは負の値を取ることが出来る(負の値は反転を意味する)。ウィンドウより大きな幅や高さを指定することも可能である。以下に使用例を示す。

stim.size = 0.8  # サイズを(0.8, 0.8)に設定したのと同じ
print(stim.size)  # array([0.8, 0.8])と出力される
stim.size += (0.5, -0.5)  # より幅広く、平らになる。
                          # サイズの値は(1.3, 0.3)になる。

実際に画面に描画される際のピクセルでの高さ、幅が必要な場合はstim._sizeRenderedを見ると良い。

texRes¶

マスクとテクスチャの解像度を設定する。値は2の冪の整数でなければならない。numpyのarrayや画像がマスクとして指定された場合はその解像度に上書きされる。+=, -=などの複合的な演算代入子に対応している。

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のままにしておくことを強く推奨する。シェーダーを使用しない/出来ない場合は刺激の色やコントラストの変更などの操作が遅くなる。

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)