TextStim¶
class psychopy.visual.TextStim(win, text='Hello World', font='',
pos=(0.0, 0.0), depth=0, rgb=None, color=(1.0, 1.0, 1.0),
colorSpace='rgb', opacity=1.0, contrast=1.0, units='',
ori=0.0, height=None, antialias=True, bold=False, italic=False,
alignHoriz='center', alignVert='center', fontFiles=(),
wrapWidth=None, flipHoriz=False, flipVert=False,
name=None, autoLog=None)
ウィンドウにテキストを描画するためのクラス。
パフォーマンスに関する補足：一般に、TextStimは他の視覚刺激オブジェクトより動作が遅い。text, height, font, boldなどの値を変化させると文字の形状が変化するパラメータを変更するときは時間を要することが多い。これらのパラメータを変更した際は myTextStim.text = myTextStim.textのようにtextの値を再設定すると次のdraw()が速くなる。
一方、pos, opacityのように文字形状が変化しない属性を変更した場合はほとんど速度に影響がない。
alignHoriz¶
水平方向のテキスト配置方法を指定する。’left’, ‘right’, ‘center’のいずれかである。
alignVert¶
垂直方向のテキストの配置方法を指定する。’top’, ‘bottom’, ‘center’のいずれかである。
antialias¶
Trueにするとアンチエイリアスを有効にする。
autoDraw¶
flipの度に自動的に刺激を描画するか否かを指定する。値はTrueかFalseである。一度設定すると再度設定するまで有効なので、flipの度にこの値を設定する必要はない。
autoLog¶
刺激の設定を変更する度に自動的にログへ出力するか否かを指定する。値はTrueかFalseである。
刺激の位置をフレーム毎に変更する場合のように、頻繁に設定を変更する場合はFalseにするとよい。
bold¶
テキストをボールド体にする。値はTrueかFalseである。ボールドのフォントを指定する方が良い。
..Make the text bold (True, False). Better to use a bold font name).
boundingBox¶
読み出し専用のデータ属性である。テキストのバウンディングボックス(描画範囲の境界を表すボックス)が(w, h)の形式で格納されている。wは幅、hは高さである。この値はsizeの値とは異なる。sizeはマージンも含んだ値であり、テキストそのものの幅とは別のものである。
..(read only) attribute representing the bounding box of the text (w,h). This differs from width in that the width represents the width of the margins, which might differ from the width of the text within them.
注：現在のバージョンではunitsの設定にかかわらずpix単位の値を返す。将来的にはunitsを反映させる予定である。
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)
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¶
このデータ属性は廃止された。刺激の重ね順は描画の順番で指定する。
flipHoriz¶
Trueならば左右反転して描画する。Falseならば通常通り描画する。反転はoriによる回転などを施す前のテキストに対して行われる。
flipVert¶
Trueならば上下反転して描画する。Falseならば通常通り描画する。反転はoriによる回転などを施す前のテキストに対して行われる。
font¶
フォント名を指定する。値は使用するシステムでフォントを特定できる文字列でなければならない。
fontFiles¶
システムの通常の位置にない追加のフォントファイルのパスを並べたリストを指定する。
例を以下に示す。
stim.fontFiles = ['SpringRage.ttf'] # load file(s)
stim.font = 'SpringRage' # set to font
height¶
文字の高さを整数または浮動小数点数で指定する。Noneならばデフォルトの値が用いられる。
Hightは文字の高さぴったりではなく、その周囲に設定されたボックス全体を含む。文字の幅は各フォントでの定義に従ってHeightの値より決定される。 +=, -=などの複合的な演算代入子に対応している。
italic¶
文字をイタリックにする。TrueまたはFalseである。イタリック体のフォントを使用する方が良い。
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度のように)丸められる。
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)
posPix¶
posやunitsの値に従って現在の刺激の位置をpix単位で計算した結果が格納されている。このあたいはposが変更されると自動的に更新される。
setAutoLog(value=True, log=None)¶
stim.autoLog = valueと同一である。ログに出力したくない場合はこちらを用いると良い。
setColor(color, colorSpace=None, operation=’‘, log=None)¶
stim.color = colorと同一である。ログに出力したくない場合や色空間を同時に指定したい場合はこちらを用いると良い。
setContrast(newContrast, operation=’‘, log=None)¶
stim.contrast = newContrastと同一である。ログに出力したくない場合はこちらを用いると良い。
setDKL(newDKL, operation=’‘)¶
バージョン1.60.05にて廃止。colorを使用すること。
setDepth(newDepth, operation=’‘, log=None)¶
このメソッドは廃止された。現在のバージョンでは刺激の重ね順はdraw()の順番で制御される。
setFlip(direction, log=None)¶
PsychoPy Builderのダイアログをシンプルにするために用意されているメソッドである。
setFlipHoriz(newVal=True, log=None)¶
stim.flipHoriz = newValと同一である。ログに出力したくない場合はこちらを用いると良い。
setFlipVert(newVal=True, log=None)¶
stim.flipVert = newValと同一である。ログに出力したくない場合はこちらを用いると良い。
setFont(font, log=None)¶
stim.font = fontと同一である。ログに出力したくない場合はこちらを用いると良い。
setHeight(height, log=None)¶
stim.height = heightと同一である。ログに出力したくない場合はこちらを用いると良い。
setLMS(newLMS, operation=’‘)¶
バージョン1.60.05にて廃止。colorを使用すること。
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と同一である。ログに出力したくない場合はこちらを用いると良い。
setText(text=None, log=None)¶
stim.text = textと同一である。ログに出力したくない場合はこちらを用いると良い。
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を見ると良い。
text¶
描画するテキストを指定する。\nで改行できる。
問題点：動作が遅い場合がある。pygletではtextの設定時にメモリリークが生じる。この問題に対処するため、TextStimの内部ではtextに代入された値を確認して以前の値から変更されている場合のみtextを更新する。したがって、フレーム毎にtextを更新するコードを書いても更新は最小限に抑制される。
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のままにしておくことを強く推奨する。シェーダーを使用しない/出来ない場合は刺激の色やコントラストの変更などの操作が遅くなる。
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)