osculari.datasets

This module manages datasets and dataloaders for psychophysical experiments.

osculari.datasets.dataset_utils

Set of utility functions in generating datasets.

osculari.datasets.dataset_utils.background_img(bg_type: Any, bg_size: Union[int, Tuple], im2double=True) → ndarray[Any, dtype[ScalarType]][source]

Create a background image based on the specified type and size.

Parameters:

  • bg_type (Any) – Type of the background. It can be a string representing a predefined type (‘uniform_achromatic’, ‘uniform_colour’, ‘random_achromatic’, ‘random_colour’, or ‘patch_colour’, ‘patch_achromatic’), or a value (int, float, list, tuple, or ndarray) representing a uniform background color.

  • bg_size (Union[int, Tuple]) – Size of the background image in pixels (height, width).

  • im2double (bool) – If True, normalize the pixel values to the range [0, 1] (default is True).

Returns:

The generated background image as a NumPy array.

Return type:

npt.NDArray

osculari.datasets.dataset_utils.random_colour(channels: Optional[int] = 3) → Sequence[source]

Generate a random color represented as a sequence of RGB values.

Parameters:

channels (Optional[int]) – Number of color channels in the generated color (default is 3).

Returns:

A sequence representing a random color, with values in the range [0, 255].

Return type:

Sequence

osculari.datasets.dataset_utils.repeat_channels(img: ndarray[Any, dtype[ScalarType]], channels: int) → ndarray[Any, dtype[ScalarType]][source]

Add channel dimension and repeat the image along the new dimension.

Parameters:

  • img (npt.NDArray) – Input image as a NumPy array.

  • channels (int) – Number of times to repeat the image along the new channel dimension.

Returns:

Image with added channel dimension and repeated along that dimension.

Return type:

npt.NDArray

osculari.datasets.geometrical_shapes

A simple generic dataset of geometrical shapes in foreground.

class osculari.datasets.geometrical_shapes.ShapeAppearanceDataset(num_samples: int, num_images: int, img_size: int, background: Any, merge_fg_bg: Callable[[List[ndarray[Any, dtype[bool]]], List[ndarray[Any, dtype[ScalarType]]]], Tuple], unique_fg_shape: Optional[bool] = True, unique_bg: Optional[bool] = True, transform: Optional[Callable] = None)[source]

Bases: Dataset

A dataset of geometrical shapes whose appearance properties can be altered.

Parameters:

  • num_samples – The total number of samples to generate.

  • num_images – The number of foreground-background pairs to generate for each sample.

  • img_size – The size of the image (int).

  • background – The background type (str or callable).

  • merge_fg_bg – A function to merge the foreground and background images (callable). This function should accept two positional arguments (foreground and background images), This function should return the merged images and corresponding ground-truth(s).

  • unique_fg_shape – Whether to use unique foreground shapes for each sample (bool; optional).

  • unique_bg – Whether to use unique background images for each sample (bool; optional).

  • transform – An optional transformation to be applied to the generated images (callable; optional).

make_bg_images() → List[ndarray[Any, dtype[ScalarType]]][source]

Generates background images.

Returns:

A list of background images (List[npt.NDArray]).

make_fg_masks() → List[ndarray[Any, dtype[bool]]][source]

Generates foreground masks with randomly positioned shapes.

Returns:

A list of foreground masks (List[npt.NDArray[bool]]).

osculari.datasets.gratings

Collection of gratings datasets common is psychophysical studies.

class osculari.datasets.gratings.GratingsDataset(img_size: int, spatial_frequencies: Optional[Sequence[int]] = None, thetas: Optional[Sequence[float]] = None, gaussian_sigma: Optional[float] = None, transform: Optional[Callable] = None)[source]

Bases: Dataset

A dataset class for generating and storing sinusoidal grating stimuli.

Parameters:

  • img_size – The desired size of the grating images (int).

  • spatial_frequencies – A list of spatial frequencies for the gratings (optional).

  • thetas – A list of orientations for the gratings (optional).

  • gaussian_sigma – The standard deviation of the Gaussian filter (optional).

  • transform – A transformation to be applied to the stimuli (optional).

make_grating(idx: int, amplitude: float, channels=3) → ndarray[Any, dtype[float]][source]

Constructs a sinusoidal grating image.

Parameters:

  • idx – The index of the grating to be generated.

  • amplitude – The amplitude of the sinusoidal modulation (float).

  • channels – The number of output channels (int; optional).

Returns:

The generated sinusoidal grating image (np.ndarray).

osculari.datasets.imutils

Image manipulation functions.

osculari.datasets.imutils.gamma_correction(img: ndarray[Any, dtype[ScalarType]], gamma: float) → ndarray[Any, dtype[ScalarType]][source]

Adjust the gamma of an image.

Parameters:

  • img (npt.NDArray) – Input image as a NumPy array.

  • gamma (float) – Gamma adjustment factor.

Returns:

Image with adjusted gamma.

Return type:

npt.NDArray

osculari.datasets.imutils.michelson_contrast(img: ndarray[Any, dtype[ScalarType]], contrast: float) → ndarray[Any, dtype[ScalarType]][source]

Adjust the contrast of an image using the Michelson contrast formula.

Parameters:

  • img (npt.NDArray) – Input image as a NumPy array.

  • contrast (float) – Contrast adjustment factor. Should be in the range [0, 1].

Returns:

Image with adjusted contrast.

Return type:

npt.NDArray