The ioHub Display Device

Platforms: Windows, OS X, Linux

class psychopy.iohub.devices.display.Display(*args, **kwargs)[source]

Bases: psychopy.iohub.devices.Device

The ioHub Display Device represents a 2D visual stimulus presentation surface that is connected to the computer running ioHub and PsychoPy. The Display Device can be queries for several run-time properties that are read when the device is created, and is also used for transforming the physical Display surface area and pixel resolution into alternative coordinate system types that can be used during an experiment.

getBounds()[source]

Get the Display’s pixel bounds; representing the left,top,right,and bottom edge of the the display screen in native pixel units.

Note

(left, top, right, bottom) bounds will ‘not’ always be (0, 0, pixel_width, pixel_height). If a multiple display setup is being used, (left, top, right, bottom) indicates the actual absolute pixel bounds assigned to that monitor by the OS. It can be assumed that right = left + display_pixel_width and bottom = top + display_pixel_height

Args:
None
Returns:
tuple: (left, top, right, bottom) Native pixel bounds for the Display.
getConfiguration()

Retrieve the configuration settings information used to create the device instance. This will be a combination of the default settings for the device (found in iohub.devices.<device_name>.default_,defice_name>.yaml, plus any device settings specified by the experiment author within an iohub_config.yaml file if the ioHubExperimentRuntime is being used to define the experiment logic, or if using the iohub.launchHubProcess() function in the experriment script, as device settings in dictionary form.

Changing any values in the returned dictionary has no effect on the device state.

Args:
None
Returns:
(dict): The dictionary of the device configuration settings used to create the device.
getCoordBounds()[source]

Get the Display’s left, top, right, and bottom border bounds, specified in the coordinate space returned by Display.getCoordinateType()

Args:
None
Returns:
tuple: (left, top, right, bottom) coordinate bounds for the Display represented in Display.getCoordinateType() units.
getCoordinateType()[source]

Returns the coordinate, or reporting unit, being used by the Display. Supported types matvh the PsychoPy unit_types for Monitors, with the exception of the height option:

  • pix : Equivelent names for this type are pixel and pixels.
  • cm : There are no equivelent alternatives to this coordinate type name.
  • norm : Equivelent names for this type are normalize and normalized.
  • deg : Equivelent names for this type are degree and degrees.

Please refer to the psychoPy documentation for a detailed description of coordinate type.

Args:
None
Returns:
str: The coordinate, or unit, type being used to define the Display stimulus area.
getDefaultEyeDistance()[source]

Returns the default distance from the particpant’s eye to the Display’s physical screen surface, as specified in the ioHub Display device’s configuration settings or the PsychoPy Monitor Configuration. Currently this is the distance from the participant’s eye of interest ( or the average distance of both eyes when binocular data is being obtained ) to the center of the Display screen being used for stimulus presentation.

Args:
None
Returns:
int: Default distance in mm from the participant to the display screen surface.
getDeviceNumber()[source]

Same as Display.getIndex(). All ioHub devices have a device_number, so for the Display Device it makes sence to map device_number to the Display index.

See Display.getIndex().

classmethod getDisplayCount()[source]

Returns the number of monitors connected to the computer that are also active. For example, a Computer may have 3 Displays connected to it, but the video card may only support having two displays active at a time.

Args:
None
Returns:
int: Total number of displays active on the computer.
getIndex()[source]

Returns the display index. In a single display configuration, this will always equal 0. In a multiple display configuration, valid index’s range from 0 to N-1, where N equals the number of display’s connected and active on the Computer being used.

Args:
None
Returns:
int: Current Display Index; between 0 and getDisplayCount()-1
getPhysicalDimensions()[source]

Returns the Display’s physical screen area ( width, height ) as specified in the ioHub Display devices configuration settings or by a PsychoPy Monitor Configuartion file.

Args:
None
Returns:
dict: A dict containing the screen ‘width’ and ‘height’ as keys, as well as the ‘unit_type’ the width and height are specified in. Currently only ‘mm’ is supported for unit_type.
getPixelResolution()[source]

Get the Display’s pixel resolution based on the current graphics mode.

Args:
None
Returns:
tuple: (width,height) of the monitor in pixels based.
getPixelsPerDegree()[source]

Returns the Display’s horizontal and vertical pixels per degree This is currently calculated using the PsychoPy built in function. Therefore PPD x and PPD y will be the same value, as only the monitor width and participants viewing distance is currently used.

The physical characteristics of the Display and the Participants viewing distance we either be based on the ioHub settings specified, or based on the information saved in the PsychoPy Monitor Configuartion file that can be optionally given to the Display Device before it is instantiated.

Args:
None
Returns:
tuple: (ppd_x, ppd_y)
getPsychopyMonitorName()[source]

Returns the name of the PsychoPy Monitor Configuration file being used with the Display.

Args:
None
Returns:
str: Name of the PsychoPy Monitor Configuration being used with the Display.
getRetraceInterval()[source]

Get the Display’s reported retrace interval (1000.0/retrace_rate)*0.001 based on the current graphics mode.

Args:
None
Returns:
float: Current retrace interval of Monitor reported by the OS in sec.msec format.
getRuntimeInfo()[source]

Returns a dictionary containing run-time determined settings for the current Display Device, based on querying system settings regarding the Monitor. Some of these values may not repesent the actual state the Display is running in if there is an issue with the Display driver or OS interface to it. The main property that should always be questioned is the Display’s reported retrace rate. An independent test should be done to determine if the reported retrace rate matches the actual rate measured.

A Display’s run-time properties consist of:

  • index: see getIndex().
  • pixel_width: The horizontal pixel resolution of the Display.
  • pixel_height: The vertical pixel resolution of the Display.
  • pixel_resolution: ( pixel_width, pixel_height )
  • bounds: See getBounds()
  • retrace_rate: The vertical retrace rate of the Display in Hz., as reported by the OS.
  • bits_per_pixel: Number if bits being used to represent all channels of a pixel by the OS.
  • primary: True if the current Monitor is also the primary monitor reported by the OS.
Args:
None
Returns:
dict: Run-time attributes of the Display, determined when the Display Device class was created by the ioHub Process.

Default Display Device Configuration Settings

# This file includes all valid Display Device
# settings that can be specified in an iohub_config.yaml
# or in Python dictionary form and passed to the quickStartHubServer
# method. Any device parameters not specified when the device class is
# created by the ioHub Process will be assigned the default value
# indicated here.
#
Display:
    
    # The unique name to assign to the evice instance created.
    # The device is accessed from within the PsychoPy script 
    # using the name's value; therefore it must be a valid Python
    # variable name as well.
    #
    name: display
    
    # The coordinate , or unit, type that the Display's surface area should
    # be represented in. Valid values are pix, deg, norm, or cm.
    #
    reporting_unit_type: pix
    
    # The Display index to assign to the device. On a single Display
    # computer this must always be 0. On a computer with multiple displays, 
    # the value can be between 0 and display_count - 1.     
    #
    device_number: 0
    
    # This section of parameters defines the actual size of the Display's 
    # 2D stimulus surface. Both width and height values are the total length of each dimention.
    # The unit_type field must currently be in mm, and therefore so must 
    # the specified width and height.
    #
    physical_dimensions:
        width: 500
        height: 281
        unit_type: mm
        
    # Enter the expected, average, distance that the participants eye(s) will
    # be from the display's stimulus surface. Currently the only supported 
    # distance reference type is surface_center, and the distance must be specified in 
    # the unit_type of mm.
    #   
    default_eye_distance:
        surface_center: 550
        unit_type: mm
    
    # If the Display device should open a PsychoPy Monitor Configuration
    # file, provide the name of it here.
    #
    psychopy_monitor_name: default
    
    # If a valid PsychoPy Monitor Configuration file 
    # has been provided, specify if the physical parameters
    # stored in it should override any duplicate parameter types
    # defined in this Display device configuartion.
    # True == Use the PsychoPy settings and update the Display config with them.
    # False == Use the measurements provided in this file and update the
    # the PsychoPy Monitor Configuration with the values specified
    # in the ioHub Device configuration.
    #
    override_using_psycho_settings: False

    # event_buffer_length: Specify the maximum number of events (for each
    #   event type the device produces) that can be stored by the ioHub Server
    #   before each new event results in the oldest event of the same type being
    #   discarded from the ioHub device event buffer.
    #
    event_buffer_length: 0

    # monitor_event_types: *If* the ioHubDataStore is enabled for the experiment, then
    #   indicate if events for this device should be saved to the
    #   monitor_event_types: Specified which Mouse Event types should be monitored
    #   for and therefore saved to the DataStore or sent to the Experiment Process.
    #
    monitor_event_types:

    #   save_events: Save Mouse events to the data_collection/Mouse event 
    #   group in the hdf5 event file.
    #   True = Save events for this device to the ioDataStore.
    #   False = Do not save events for this device in the ioDataStore.
    #
    save_events: False

    # streamEvents: Indicate if events from this device should be made available
    #   during experiment runtime to the Experiment / PsychoPy Process.
    #   True = Send events for this device to  the Experiment Process in real-time.
    #   False = Do *not* send events for this device to the Experiment Process in real-time.
    #
    stream_events: False

    # auto_report_events: Indicate if events from this device should start being
    #   processed by the ioHub as soon as the device is loaded at the start of an experiment,
    #   or if events should only start to be monitored on the device when a call to the
    #   device's enableEventReporting method is made with a parameter value of True.
    #   True = Automatically start reporting events for this device when the experiment starts.
    #   False = Do not start reporting events for this device until enableEventReporting(True)
    #       is set for the device during experiment runtime.
    #
    auto_report_events: False

    # The Display device model name can be specified here.
    # It is not used by the ioHub, so is FYI only.
    #
    model_name: N/A
    
    # The Display device model number can be specified here.
    # It is not used by the ioHub, so is FYI only.
    #
    model_number: N/A
    
    # The Display device manufacturer's name can be specified here.
    # It is not used by the ioHub, so is FYI only.
    #
    manufacturer_name: N/A
    
    # The Display device serial number can be specified here.
    # It is not used by the ioHub, so is FYI only.
    #
    serial_number: N/A
    
    # The date of manufactiurer for the Display device 
    # can be specified here. It is not used by the ioHub,
    # so is FYI only.
    #   
    manufacture_date: DD-MM-YYYY

    # The Display device's hardware version can be specified here.
    # It is not used by the ioHub, so is FYI only.
    #
    hardware_version: N/A
    
    # If the Display devicehas firmware, its revision number
    # can be indicated here.
    # It is not used by the ioHub, so is FYI only.
    #
    firmware_version: N/A

    # software_version: The device driver and / or SDK software version number.
    #   This field is not used by ioHub, so is FYI only. 
    #
    software_version: N/A

Display Device Events

The Display Device does not generate any ioHub Events.

Notes and Considerations

None at this time.