Window¶

class psychopy.visual.Window(size=(800, 600), pos=None, color=(0, 0, 0),
    colorSpace='rgb', rgb=None, dkl=None, lms=None, fullscr=None,
    allowGUI=None, monitor=None, bitsMode=None, winType=None, units=None,
    gamma=None, blendMode='avg', screen=0, viewScale=None, viewPos=None,
    viewOri=0.0, waitBlanking=True, allowStencil=False, multiSample=False,
    numSamples=2, stereo=False, name='window1', checkTiming=True,
    useFBO=False, useRetina=False, autoLog=True)

pygletまたはpygameをバックエンドとして使用して、刺激描画用のウィンドウを作成する。

pygletを用いると複数のウィンドウを作成し、目的に応じてどのウィンドウを用いるか指定して使用することが出来る。また、動画のレンダリングも可能である。 pygameは以前のバージョンのPsychoPyで使用されていたもので、現在のバージョンのPsychoPyでも使用することはできるがサポートは廃止予定である。pygameに固有のバグは今後修正されない。

以下の属性はオブジェクトの初期化時のみ設定できる。初期化後に変更可能な属性のリストは後で示す。

パラメータ	解説
size	ウィンドウの大きさ。単位はピクセル。デフォルト値は(800, 600)
pos	スクリーン上におけるウィンドウの位置。(100,200)のように座標で指定する。
color	ウィンドウの背景色。RGBの値を[0,0,0]のように示すか色名などで指定する。デフォルト値は[0,0,0]。 RGBの各成分は-1.0から1.0で指定する。
fullscr	フルスクリーンモードの指定。一般にフルスクリーンモードの方が描画タイミングが正確である。 Trueならフルスクリーン、Falseならウィンドウモード。NoneならPsychoPyの設定に従う。
allowGUI	ウィンドウの枠やタイトルの描画の指定。Falseならこれらのものを描画しない。NoneならPsychoPyの設定に従う。
winType	バックエンドの指定。’pyglet’または’pygame’。NoneならPsychoPyの設定に従う。
monitor	実験に使用するモニターの指定。psychopy.monitors.Monitorオブジェクトで指定する。
units	刺激の描画時に標準で使用する単位の指定。’height’、’norm’、’deg’、’cm’、’pix’、’degFlat’、’degFlatPos’ のいずれかを指定する。NoneならPsychoPyの設定に従う。
screen	使用するモニターの指定。0がプライマリ、1がセカンダリ(以後2, 3,...と接続モニター台数-1まで)。 winTypeがpygletの場合のみ有効。
viewScale	刺激描画時の単位をスケーリングする。Noneならスケーリングなし、(x, y)なら横方向にx倍、縦方向にy倍。
viewPos	刺激描画時の座標の原点を変更する。単位はウィンドウの標準の単位に従う。Noneなら変更なし。(x, y)形式で指定。
viewOri	刺激描画時の座標を回転させる。単位はdeg。Noneなら回転なし。
waitBlanking	Trueならflip()が垂直同期を待つ。Falseなら待たない。 NoneならPsychoPyの設定に従う。
bitsMode	1.80.02にて廃止。pycrsltdのBitsSharpクラスを使用すること。
checkTiming	TrueまたはFalse。Trueなら初期化時にフレーム間時間の確認を行う。結果はデータ属性 monitorFramePeriod に保存される。Falseなら確認を行わない。
allowStencil	TrueまたはFalse。TrueならばOpenGLのステンシルバッファを使用する。psychopy.visual.Apertureオブジェクトを使用するために必要である。
multiSample	TrueまたはFalse。Trueに設定した場合、マルチサンプルバッファーを有効にする。使用しているグラフィックドライバがこの機能をサポートしていなければ無効である。 winTypeがpygletの場合のみ利用できる。
numSamples	2以上の整数を指定する。multiSampleが有効な時に、各ピクセルのサンプルサイズを指定する。サイズが大きいほど画質は向上するが、flipの遅延が増大する恐れがある。最大値はGL_MAX_SAMPLESによって決定され、通常16または32 である。不適切な値が指定されるとクラッシュする。
stereo	TrueまたはFalse。Trueに設定した場合、setBuffer()を用いて右眼用と左眼用の刺激を切り替えて描画して3D表示を行うことが出来る。グラフィックカードがクアッドバッファーによる3D表示に対応している必要がある。
useRetina	TrueまたはFalse。TrueならばRetinaディスプレイの本来の解像度を利用しようとする。標準(False)ではHiDPI表示が用いられる。
blendMode	ブレンドモード(‘avg’または’add’)を設定する。’avg’ならば不透明度aの刺激を描画したときに、刺激の色と背景の色をa:1-aの比で混色する。’add’ならば加法混色を行う。

callOnFlip(function, *args, **kwargs)¶

flip()の直後に実行する関数を設定する。

第1引数は呼び出される関数、第2引数以降は第1引数に指定した関数に渡す引数を順番に並べる。例えば、通常は以下のように呼び出す関数があるとする。

pingMyDevice(portToPing, channel=2, level=0)

この関数をcallOnFlip()を用いてflip()と同期して呼び出すためには以下のようにする。

win.callOnFlip(pingMyDevice, portToPing, channel=2, level=0)

clearBuffer()¶

フリップをせずにバックバッファ(=現在描画中のバッファ)をクリアする。刺激画像の動画を作成するときに、flip()を行わずに次のフレームの描画を開始できるので便利である。

close()¶

ウィンドウを閉じる。必要があればBits++をリセットする。

color¶

ウィンドウの背景色を設定する。

このメソッドを実行した直後ではなく、次のバッファクリアの後から効果が合わられる点に注意。すなわち、このメソッドの効果が画面上に反映されるには ** 2回 ** flip()を行う必要がある(1回目でバックバッファの色が変更された状態でクリアされ、2回目で表示される)。従って、背景色をリアルタイムに(on-the-fly)変更したい場合は、ウィンドウと同じサイズのvisual.Rectオブジェクトを他の刺激の背後に置いて、このRectオブジェクトの属性fillColorを変更するほうが良いだろう。

colorSpace¶

色空間を表す文字列を指定する。

通常、以下のようにcolorと合わせて設定する。

win.colorSpace = 'rgb255'  # 色空間をRGB255に変更
win.color = [0, 0, 255]    # RGB255での「青」

dispatchAllWindowEvents()¶

全てのpygletウィンドウのイベントを処理する。iohub 2.0のPsychoPyキーボードイベントへの統合のために用いられる。

flip(clearBuffer=True)¶

フロントバッファとバックバッファをフリップする。旧バージョンのwin.update()を置き換えるもので、実際に行っている処理をより正確に反映した名前となった。引数clearBufferをFalseにするとバックバッファのクリアを行わない。

fps()¶

最後にこのメソッドが実行されてから現在までの1秒間のフレーム数を返す。ウィンドウ作成後このメソッドが初めて実行された場合はウィンドウ作成からの値を返す。

gamma¶

モニターのガンマ値を設定する。モニタープロファイルの設定値より優先される。Bits++やBits#を使用しているときはこのメソッドを使用してはいけない。

gammaRamp¶

(解説なし)

getActualFrameRate(nIdentical=10, nMaxFrames=100, nWarmUpFrames=10, threshold=1)¶

スクリーンのFPSを計測する。

1フレームの時間が同一と見なされる(thresholdで設定された標準偏差以下)nIdentila回の連続したフレームを取得し、FPSを計算する。nMaxFrames回flipする間に同一と見なされるフレーム時間が得られなかった場合は計測は失敗し、ログファイルに警告が出力されて戻り値はNoneとなる。

This is done by waiting (for a max of nMaxFrames) until [nIdentical] frames in a row have identical frame times (std dev below [threshold] ms).

パラメータ	解説
nIdentical	計測の対象となる連続したフレーム数。大きい値ほど正確だが、時間を要する。
nMaxFrames	nIdenticalで指定したサンプルが得られるまで繰り返すフレーム数の最大値。
nWarmUpFrames	サンプルを採取し始める前に表示するフレーム数 (ウィンドウが作成されてから「落ち着く」までの時間を確保するため)。
threshold	サンプル内で時間が一致していると判定される最大の標準偏差。

getMovieFrame(buffer=’front’)¶

現在のウィンドウを画像としてキャプチャする。

キャプチャした画像はsaveMovieFrames()でファイルに保存できる。バージョン1.81.00からは、戻り値としてキャプチャした画像がPILのImageオブジェクトとして得られる。

このメソッドはいつでも実行できるが、通常はflip()の実行後に実行すればよい。

キャプチャされた画像は、saveMovieFrame()が実行されるまでメモリ上に保持される。目的に応じて必要なタイミングでgetMovieFrame()を実行して、最後にまとめて出力すればよい。

引き数にバックバッファを指定した場合は、まだflipされていない画像がキャプチャされる。これは不便な場合もあるが、マウスや他のウィンドウなどが重ね書きされる前の画像が得られるという利点がある。

引き数に(デフォルト値の)フロントバッファを指定した場合はflip()の直後に実行するとよい。フロントバッファの場合はモニター上に描かれているままのコピーが保存される。

getMsPerFrame(nFrames=60, showVisual=False, msg=’‘, msDelay=0.0)¶

現在のモニターのリフレッシュレート(平均値、中央値、標準偏差)を最低60フレーム以上にわたって評価する。

nFrames(60以上)回のフレームのリフレッシュ時間を記録する。showVisualがTrueの場合はアニメーションが描画される。このアニメーションには特に意味はないが、計測中であることが視覚的にわかりやすい。msgに文字列を指定することで、計測中であることを示すメッセージを表示させることも出来る。msgに値を指定した場合はshowVisualの値はFlaseと見なされる。

CPUに負荷がかかっている時のリフレッシュレートをシミュレートするには、msDelayに値を指定することによってflip()を開始するまでの遅延を設定することが出来る(単位はms)。

戻り値は1フレームの時間の(平均値, 標準偏差, 中央値)である。平均値と標準偏差は全フレームの測定値を使用するが、中央値は全フレームの中央値の近傍12フレームの時間の平均値である。

logOnFlip(msg, level, obj=None)¶

次のflip()実行時にタイムスタンプ付きのメッセージをログファイルに送信する。

パラメータ	解説
msg	ログファイルに出力するメッセージ
level	ログのレベル
obj	(任意) このメッセージに関連するPythonオブジェクト

mouseVisible¶

マウスカーソルの可視、不可視をTrue、Falseで指定する。

ウィンドウがallowGUI=Falseで初期化された場合はマウスカーソルは不可視に設定されるが、それ以外の場合は可視に設定される。

recordFrameIntervals¶

フレーム間時間の計測を開始または停止する。

フレーム間時間とはflip()から次のflip()までの時間のことである。時間的精度が特に要求される期間にはこの値をTrueに設定する。画面を更新しない時にはこの値をFalseに設定する。具体的には、試行と試行の間や event.waitkeys()、core.wait()、image.setImage()などを実行する時である。

Window.saveFrameIntervals()も参照のこと。

saveFrameIntervals(fileName=None, clear=True)¶

記録されたフレーム間時間をCSVファイルとして保存する。引数fileNameにファイル名を指定する。必要に応じて絶対パス、相対パスを用いることが出来る。Noneを指定した場合はlastFrameIntervals.logというファイル名が用いられる。

saveMovieFrames(fileName, codec=’libx264’, fps=30, clearFrames=True)¶

キャプチャした画像をディスクに保存する。PILが対応しているフォーマット(tif, jpg, png...)で保存できる。

パラメータ	解説
filename	ファイル名。パスを含むことが出来る。ファイル名の拡張子によってフォーマットが決定される。画像フォーマット(pngなど)が指定された場合は、キャプチャした画像と同じ数の画像ファイルが作成される。 .gifが指定された場合はアニメーションGIFファイルが作成される。 WindowsおよびLinuxではpymediaがインストールされていれば拡張子.mpegでMPEGファイルを作成できる。OS Xではpyobjc-frameworks-QTKitがインストールされていれば拡張子.movでMOVファイルを作成できる。
codec	動画での保存時にmoviepyがmp4/mpg/movファイルを作成するために用いるコーデックを指定する。
fps	動画のフレームレート(MOVファイル)。
clearFrames	Trueなら保存後にメモリ上のキャプチャ画像は消去される。残しておく必要がある場合はFalseにする。

残念ながら、動画で出力する場合の品質は高くない。アニメーションGIFの場合は、各フレームをPNGで画像として出力してffmpegやimagemagick、GIMPのようなソフトウェアで動画にする方がよい結果が得られる。

動画のコーデックにNoneが指定された場合は拡張子に応じてコーデックが選択される。MP4およびMOVファイルではlibx264, mpeg4が使用される。AVIファイルの場合はrawvideo, pngが使用される(AVIファイルは非推奨)。OGVファイルではlibvorbisが使用される。

以下に使用例を示す。

# 画像をTIFFファイルとして出力する。複数フレームがキャプチャされて
# いる場合はframe001.tif, frame002.tif...と連番で保存される。
myWin.saveMovieFrames('frame.tif')

# PsychoPy 1.84.1 ではmoviepyを用いて以下のような出力が可能である。
myWin.saveMovieFrames('stimuli.mp4') # codecは'libx264'または'mpeg4'
myWin.saveMovieFrames('stimuli.mov')
myWin.saveMovieFrames('stimuli.gif')

setBlendMode(blendMode, log=None)¶

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

setBuffer(buffer, clear=True)¶

3D表示モードにおいて操作するバッファを’left’または’right’に切り替える。

ウィンドウがstereo=Trueで初期化されていて、グラフィックカードが(nVidiaのQuadroシリーズのように)クアッドバッファリングによる3D表示をサポートしている必要がある。

使用例を示す。

win = visual.Window(...., stereo=True)
while True:
    win.setBuffer('left', clear=True)
    # 左眼用の刺激を描く
    win.setBuffer('right', clear=True)
    # 右眼用の刺激を描く
    win.flip()

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

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

setGamma(gamma, log=None)¶

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

setMouseVisible(visibility, log=None)¶

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

setRGB(newRGB)¶

バージョン1.61.00で廃止された。setColor()を用いること。

setRecordFrameIntervals(value=True, log=None)¶

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

setScale(units, font=’dummyFont’, prevScale=(1.0, 1.0))¶

以前は刺激描画の単位の切り替えに使用されていたが、現在では ** 廃止 ** されたメソッドである。

setUnits(value, log=True)¶

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

setViewPos(value, log=True)¶

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

units¶

None, ‘height’, ‘norm’, ‘deg’, ‘cm’, ‘pix’, ‘defFlat’, ‘degFlatPos’のいずれかを指定する。このウィンドウ上に作成する刺激の単位はこの値に従う。刺激作成後にunitsの値を変更しても、すでに作成図にも刺激の単位は自動的には変化しない。unitsは刺激ごとに「上書き」出来る。

viewPos¶

刺激を描画する際の原点を指定する。値はウィンドウに設定された単位が適用される。値を変更する際はX座標のみ、Y座標のみではなく両方をまとめて一度に変更する必要がある。

win.viewPos = [new_xval, new_yval] # 適切な方法
win.viewPos[0] = new_xval # X, Yの一方の値だけ変更は不可！

waitBlanking¶

None、TrueまたはFalseを指定する。