RadialStim

class psychopy.visual.RadialStim(win, tex='sqrXsqr', mask='none',
    units='', pos=(0.0, 0.0), size=(1.0, 1.0), radialCycles=3,
    angularCycles=4, radialPhase=0, angularPhase=0, ori=0.0,
    texRes=64, angularRes=100, visibleWedge=(0, 360), rgb=None,
    color=(1.0, 1.0, 1.0), colorSpace='rgb', dkl=None, lms=None,
    contrast=1.0, opacity=1.0, depth=0, rgbPedestal=(0.0, 0.0, 0.0),
    interpolate=False, name=None, autoLog=None, maskParams=None)

放射状の視覚刺激、すなわち環(annulus)状、楔(wedge)状のチェッカーボードを描画するクラスである。fMRIでレチノトピーを確認する刺激として便利である。GratingStimを基に多くの機能が盛り込まれている。

この刺激は比較的新しく追加されたもので、時折おかしな表示となる場合がある。また、一般的なGratingStimによる刺激より描画に時間を要するため、高フレームレートを要する課題には推奨できない。

angularCycles

円周方向のパターンの繰り返し回数を指定する。浮動小数点数を指定できるが、整数がよい。+=, -=などの複合的な演算代入子に対応している。

angularPhase

円周方向の位相を指定する。値は浮動小数点数で、0.0から1.0の範囲に丸められる。

これはラジアンでテクスチャの回転角度を指定することと似ている。可能であれば、oriを使って回転させる方が効率的である。+=, -=などの複合的な演算代入子に対応している。

angularRes

刺激を描画するために用いる三角形の個数を指定する。+=, -=などの複合的な演算代入子に対応している。

(訳注：RadialStimでは円を多数の三角形に分割して描画している。分割数を多くするほど滑らかな円に近づく。)

autoDraw

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

autoLog

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

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

clearTextures()

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

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

interpolate

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

mask

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

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

RadialStimにおけるmaskはImageStimとは幾分異なる点に注意。RadialStimにおいては1xNのarrayオブジェクトは刺激の中心から外側に向かっての輝度プロファイルに対応する。

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デモ

phase

テクスチャのX方向及びY方向の位相を指定する。値はX, Yの値を並べたシーケンスかスカラーである。

位相は(360や2 * piではなく)1を法とする点に注意。これは一般的ではないが位相にt * nを設定することによってn Hzのドリフトになるという利点がある。

(訳注：ここで「1を法とする」とは1で割った余りの値となるという意味だと考えておけばよい。すなわち1.78は0.78と同一である。また、ここでpsychopy.core.ClockのgetTime()の戻り値ように秒の単位で現在時刻を格納している変数である。)

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)

radialCycles

中心から周辺に向かってテクスチャが繰り返される回数を指定する。浮動小数点数を指定できるが、整数がよい。+=, -=などの複合的な演算代入子に対応している。

radialPhase

中心から円周方向の位相を指定する。値は浮動小数点数で、0.0から1.0の範囲に丸められる。同心円状に内側へ、あるいは外側へのドリフトを描画するのに使用できる。+=, -=などの複合的な演算代入子に対応している。

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

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

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

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

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()の順番で制御される。

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と同一である。ログに出力したくない場合はこちらを用いると良い。

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

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

(訳注：原文ではこのメソッドは「廃止」となっている)

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

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

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

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

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

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

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

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

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

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

(訳注：原文ではこのメソッドは「廃止」となっている)

setSize(newSize, operation=’‘, units=None, log=None)

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

setTex(value, log=None)

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

(訳注：原文ではこのメソッドは「廃止」となっている)

setUseShaders(value=True, log=None)

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

sf

X方向及びY方向の空間周波数を指定する。値はX, Yの値を並べたシーケンスかスカラー、あるいはNoneである。

unitsが’deg’ならばcycles/deg、’cm’ならばcycles/cmとなる。’norm’の場合は、刺激における繰り返し回数となる(すなわちsf=3ならばsizeに関わらず3回繰り返される)。texがファイルから読み込まれた画像の場合、sfにNoneを設定すると空間周波数は「1/刺激サイズ」に設定され、画像が1サイクル表示される。

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を見ると良い。

tex

グレーティング刺激の描画に用いるテクスチャを指定する(キャリアとも呼ばれる)。さまざまなオプションを指定できる。

• ‘sin’: 正弦波
• ‘sqr’: 矩形波
• ‘saw’: 鋸波
• ‘tri’: 三角波
• None: なし(一様)
• ファイル名: PILで読み込めるフォーマットの画像
• NumPyのarrayオブジェクト: 1xNまたはNxNで値が-1.0から1.0のもの

画像やNumPyのarrayオブジェクトを用いる場合は、2の冪の正方形のもの(例えば256x256)を用いること。この条件に合致しない場合、最も近い2の冪の正方形になるように拡大される。

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に基づいてピクセルに計算した結果を保持している。

visibleWedge

楔形の開始角度と終了角度を(start, end)のシーケンスで指定する。単位は度である。(0, 360)で円全体が表示される。+=, -=などの複合的な演算代入子に対応している。

(訳注：oriなどと異なり0未満、360より大きい値は使用できない。また、start <= endでなければならない。)

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)