feat(sbcs): sbcs.circular, .square

Pass-through wrappers based off `bullseyes.<>`

stimupy/stimuli/sbcs.py

@@ -1,11 +1,14 @@
 import numpy as np
 
 from stimupy.components.shapes import disc, rectangle
+from stimupy.stimuli import bullseyes
 from stimupy.utils import make_two_sided, pad_by_visual_size, pad_to_shape, resolution
 
 __all__ = [
     "generalized",
     "basic",
+    "square",
+    "circular",
     "basic_two_sided",
     "with_dots",
     "with_dots_two_sided",
@@ -133,6 +136,126 @@ def basic(
     return stim
 
 
+def square(
+    target_radius,
+    visual_size=None,
+    ppd=None,
+    shape=None,
+    surround_radius=None,
+    rotation=0.0,
+    intensity_surround=0.0,
+    intensity_background=0.5,
+    intensity_target=0.5,
+    origin="mean",
+):
+    """Simultaneous contrast stimulus with square target and surround field
+
+    Parameters
+    ----------
+    visual_size : Sequence[Number, Number], Number, or None (default)
+        visual size [height, width] of image, in degrees
+    ppd : Sequence[Number, Number], Number, or None (default)
+        pixels per degree [vertical, horizontal]
+    shape : Sequence[Number, Number], Number, or None (default)
+        shape [height, width] of image, in pixels
+    target_radius : float
+        radius of target, in degrees visual angle
+    surround_radius : float
+        radius of surround context field, in degrees visual angle
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizonal)
+    intensity_surrond : float, optional
+        intensity of surround context field, by default 0.0
+    intensity_background : float, optional
+        intensity value of background, by default 0.5
+    intensity_target : float, or Sequence[float, ...], optional
+        intensity value for each target, by default 0.5.
+    origin : "corner", "mean" or "center"
+        if "corner": set origin to upper left corner
+        if "mean": set origin to hypothetical image center (default)
+        if "center": set origin to real center (closest existing value to mean)
+
+    Returns
+    -------
+    dict[str, Any]
+        dict with the stimulus (key: "img"),
+        mask with integer index for each frame (key: "target_mask"),
+        and additional keys containing stimulus parameters
+    """
+    stim = bullseyes.rectangular_generalized(
+        radii=(target_radius, surround_radius),
+        visual_size=visual_size,
+        ppd=ppd,
+        shape=shape,
+        rotation=rotation,
+        intensity_frames=(0.0, intensity_surround),
+        intensity_background=intensity_background,
+        intensity_target=intensity_target,
+        origin=origin,
+    )
+    return stim
+
+
+def circular(
+    target_radius,
+    visual_size=None,
+    ppd=None,
+    shape=None,
+    surround_radius=None,
+    intensity_surround=0.0,
+    intensity_background=0.5,
+    intensity_target=0.5,
+    origin="mean",
+):
+    """Simultaneous contrast stimulus with circular target and surround field
+
+    Parameters
+    ----------
+    visual_size : Sequence[Number, Number], Number, or None (default)
+        visual size [height, width] of image, in degrees
+    ppd : Sequence[Number, Number], Number, or None (default)
+        pixels per degree [vertical, horizontal]
+    shape : Sequence[Number, Number], Number, or None (default)
+        shape [height, width] of image, in pixels
+    target_radius : float
+        radius of target, in degrees visual angle
+    surround_radius : float
+        radius of surround context field, in degrees visual angle
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizonal)
+    intensity_surrond : float, optional
+        intensity of surround context field, by default 0.0
+    intensity_background : float (optional)
+        intensity value of background, by default 0.5
+    intensity_target : float, or Sequence[float, ...], optional
+        intensity value for each target, by default 0.5.
+        Can specify as many intensities as number of target_indices;
+        If fewer intensities are passed than target_indices, cycles through intensities
+    origin : "corner", "mean" or "center"
+        if "corner": set origin to upper left corner
+        if "mean": set origin to hypothetical image center (default)
+        if "center": set origin to real center (closest existing value to mean)
+
+    Returns
+    -------
+    dict[str, Any]
+        dict with the stimulus (key: "img"),
+        mask with integer index for each frame (key: "target_mask"),
+        and additional keys containing stimulus parameters
+    """
+    stim = bullseyes.circular_generalized(
+        radii=(target_radius, surround_radius),
+        visual_size=visual_size,
+        ppd=ppd,
+        shape=shape,
+        intensity_rings=(0.0, intensity_surround),
+        intensity_background=intensity_background,
+        intensity_target=intensity_target,
+        origin=origin,
+    )
+    return stim
+
+
 basic_two_sided = make_two_sided(
     basic, two_sided_params=("target_size", "intensity_target", "intensity_background")
 )
@@ -436,6 +559,9 @@ def overview(**kwargs):
     stimuli = {
         "sbc_generalized": generalized(**default_params, visual_size=10, target_size=(3, 4), target_position=(1, 2)),
         "sbc_basic": basic(**default_params, visual_size=10, target_size=3),
+        "sbc_square": square(**default_params, visual_size=10, target_radius=1, surround_radius=2),
+        "sbc_circular": circular(**default_params, visual_size=10, target_radius=1, surround_radius=2),
+
         "sbc_2sided": basic_two_sided(**default_params, visual_size=10, target_size=2, intensity_background=(0.0, 1.0)),
         "sbc_with_dots": with_dots(**default_params, **dot_params),
         "sbc_with_dots_2sided": with_dots_two_sided(**default_params, **dot_params, intensity_background=(0.0, 1.0), intensity_dots=(1.0, 0.0)),