DotStim
=====================================

.. code-block:: python

    class psychopy.visual.DotStim(win, units='', nDots=1, coherence=0.5,
        fieldPos=(0.0, 0.0), fieldSize=(1.0, 1.0), fieldShape='sqr',
        dotSize=2.0, dotLife=3, dir=0.0, speed=0.5, rgb=None,
        color=(1.0, 1.0, 1.0), colorSpace='rgb', opacity=1.0, contrast=1.0,
        depth=0, element=None, signalDots='same', noiseDots='direction',
        name=None, autoLog=None)

DotStimは一面に多数のドットを描画するためのクラスである。draw()の呼び出しの度にどのようにドットの位置を更新するかを指定することが出来る。

DotStimは多様なドットの運動に対応している。各方法の長所と短所はScase, Braddick & Raymond (1996)を参照のこと。この文献で述べられている6種類の運動全てがsignalDots, noiseDots, dotLifeを適切に設定することで描画できる。

============= ============================================================================================================
パラメータ    解説
============= ============================================================================================================
signalDots    'same'または'different'。信号のドットがフレーム毎に異なるドットとなるか同一のドットとなるかを指定する。
noiseDots     'direction', 'position','walk'のいずれか。ノイズのドットの更新規則を指定する。
dotLife       ドットが消滅するまでのフレーム数を指定する。
============= ============================================================================================================

バージョン1.70.00以降では、デフォルト値ではノイズは一定の速度でランダムな方向に運動し、信号は同じドットであり続ける。

詳細についてはPsychoPy BuilderのDotsコンポーネントのドキュメントを参照のこと。

さらにカスタマイズが必要な場合は、DotStimから派生クラスを作成して_update_dotsXYと_newDotsXYメソッドをオーバーライドすること。

(訳注：原文にはthe DotStim should be subclassedとある)

ドット描画範囲はfieldSizeで決定される。fieldSizeにはX方向とY方向の大きさを表す要素数2のシーケンスか、スカラーを指定する。スカラーの場合はX方向、Y方向同サイズを指定したものと解釈される。値は負の数でもよいし、ウィンドウより大きくてもよい。

.. This stimulus class defines a field of dots with an update rule that determines how they change on every call to the .draw() method.

.. This single class can be used to generate a wide variety of dot motion types. For a review of possible types and their pros and cons see Scase, Braddick & Raymond (1996). All six possible motions they describe can be generated with appropriate choices of the signalDots (which determines whether signal dots are the ‘same’ or ‘different’ on each frame), noiseDots (which determines the locations of the noise dots on each frame) and the dotLife (which determines for how many frames the dot will continue before being regenerated).

.. The default settings (as of v1.70.00) is for the noise dots to have identical velocity but random direction and signal dots remain the ‘same’ (once a signal dot, always a signal dot).

.. For further detail about the different configurations see Dots (RDK) Component in the Builder Components section of the documentation.

.. If further customisation is required, then the DotStim should be subclassed and its _update_dotsXY and _newDotsXY methods overridden.

..    Parameters:	

..    fieldSize
..    : (x,y) or [x,y] or single value (applied to both dimensions). Sizes can be negative and can extend beyond the window.