stelaCSF: A unified model of contrast sensitivity as the function of Spatio-Temporal frequency, Eccentricity, Luminance and Area

This repository contains both the code and the data for a contrast sensitivity model, as the function of

• spatial frequency in cycles per degree
• temporal frequency in Hz
• eccentricity in visual degrees
• lumunance in cd/m^2 (or nit)
• area in squared visual degrees

The detais about the model and the dataset can be found on the project web site and in the paper:

Mantiuk, Rafał K, Maliha Ashraf, and Alexandre Chapiro. “StelaCSF - A Unified Model of Contrast Sensitivity as the Function of Spatio-Temporal Frequency , Eccentricity , Luminance and Area.” ACM Transactions on Graphics 41, no. 4 (2022): 145. https://doi.org/10.1145/3528223.3530115

Code

Currently the code is provided as a Matlab class in the directory matlab.

Example

To plot the CSF as the function of temporal frequency:

clf;

csf_model = CSF_stelaCSF();
t_freq = linspace( 0, 60 )'; %Hz, must be a column vector
csf_pars = struct( 's_frequency', 4, 't_frequency', t_freq, 'orientation', 0, 'luminance', 100, 'area', 1, 'eccentricity', 0 );          
S = csf_model.sensitivity( csf_pars );        

plot( t_freq, S );
set( gca, 'YScale', 'log' );
xlabel( 'Temporal frequency [Hz]' );
ylabel( 'Sensitivity' );

Check also `matlab/example_plot_csf.m'.

Data

Each datapoint represent a Gabor patch at the detection threshold, either for individual observer, or averaged across all observers. The sensitivity is averaged the log-contrast space.

The data is stored in the CSV files:

• data/data_individual.csv - measurements for individual participants.

If no individual data is available in a dataset/paper, it is excluded from data_individual.csv.

• data/data_aggregated.csv - the sensitivities averaged across the participants.

The columns are identical as in data_individual.csv but without the columns observer and age.

• data/backgrounds.csv - the LMS coordinates of the background/adaptation colour

The background IDs are unique across all datasets so that the tables data* and backgrounds can be merged using bkg_id as the key.

bkg_id - the unique ID of the background colour L, M, S - LMS colour coordinates R - rod response or scotopic luminance (CIE 1951 scotopic luminous function) bkg_label - string label of the background (e.g. 'red', 'white', 'd65') dataset - the ID of the dataset

• data/color_direction.csv - the LMS colour vector representing the colour axis along which the stimulus (Gabor) was modulated

The colour directions IDs are unique across all datasets so that the tables data* and color_direction can be merged using color_direction as the key.

col_dir_id - the unique ID of the colour direction L_delta ,M_delta, S_delta - the vector defining the direction in the LMS colour space dataset - the ID of the dataset

• data/data_individual_merged.csv - the same as data_individual.csv but merged with both backgrounds.csv and color_direction.csv.

• data/data_aggregated_merged.csv - the same as data_aggregated.csv but merged with both backgrounds.csv and color_direction.csv.

• data/datasets.json - metadata of each dataset

Columns:

• observer - The anonymized unique ID of an observer. Some observers can be common across the datasets.
• age - age of the observer in years. NaN if it is unknown.
• luminance - luminance in cd/m^2, using standard CIE luminous efficiency function (or Y of CIE 1931 XYZ)
• s_frequency - spatial frequency in cycles per degree
• t_frequency - temporal frequency in cycles per degree
• orientation - spatial orientation of the stimulus in degrees
• col_dir_id - the ID of the colour direction. The LMS vectors of the colour directions are stored in color_direction.csv.
• bkg_id - the ID of the background colour. The LMS coordinates of the background colour can be found in backgrounds.csv.
• ge_sigma - the standard deviation of the Gaussian envelope the limits the size of the Gabor patch
• ge_lambda - the number of cycles within the 1 standard deviation radius, computed as 2 * ge_sigma * frequency
• area - the area of the stimulus in deg^2. For regular Gabor patches it is computed as pi*ge_sigma^2
• log_cone_contrast - the log10 of cone contrast at the detection threshold
• var_log_cone_contrast - the variance of the log_cone_contrast. NaN if the variance for individual measurements is not available. The variance is typically estimated when fitting a psychopmetric function to nAFC measurements.
• dataset - the ID of the dataset
• eccentricity - distance from the central foveal point in visual degrees
• vis_field - the angle that defines the position in the visual field at certain eccentricity. The values: 0 - temporal (horizontal, away from the nose); 90 - superior (vertical, top) 180 - nasa (horizontal, toward the nose) 240 - inferior (vertical, bottom) The values are equivalent to the polar coordinates for the right eye.