New open-source Python toolbox simplifies grid sampling for researchers

Every experiment in vision science begins with an image, and increasingly, it also begins with a way of cutting that image into pieces. Whether researchers are asking how the brain stitches fragmented scene views into a coherent whole, how eye movements land on meaningful regions of a photograph, or how a computer vision algorithm learns from parts of a picture, they almost invariably need to sample local regions and relate them to global structure. The most common tool for that job is deceptively simple: overlay a grid on the image and treat each cell as a region. Yet behind that simplicity has long lain a persistent methodological problem. Grid sampling is so basic that nearly every laboratory writes its own quick-and-dirty implementation, producing a patchwork of ad hoc, study-specific code that resists comparison across papers and often defeats newcomers trying to reproduce published stimuli. A new open-source toolbox called GridSamp, described by Maarten Leemans, Christophe Bossens, and Johan Wagemans of the Brain and Cognition research unit at KU Leuven in Belgium, aims to end that fragmentation by turning grid sampling into a standardized, transparent, and flexible Python workflow.

The paper, published in Behavior Research Methods as an original manuscript, frames the problem in terms of reproducibility and accessibility. Because grid sampling has typically been implemented ad hoc, the parameters that matter — how many rows and columns the grid contains, where the grid starts relative to the image, what shape each sampled region takes, whether the region includes surrounding context — are often underreported or buried in unpublished scripts. Two studies that both claim to have used “a 4 × 4 grid” may in fact have produced very different stimuli if the grids were offset differently, if cell boundaries overlapped or left gaps, or if regions were extracted as rectangles versus masks. GridSamp addresses this by making every one of those parameters explicit, user-definable, and encoded in a single, publicly available codebase, so that stimulus generation can be described, shared, and repeated exactly.

At its core, GridSamp automates the process of overlaying a grid with a predefined number of rows and columns onto an image and extracting the content of each cell as an image region. But the toolbox goes well beyond a naive slicing operation. It supports multiple grid types, each with user-defined parameters, and it allows researchers to specify the starting position of the grid, controlling precisely how cells align with image content. This matters more than it might appear: the phase of a grid relative to an object can determine whether that object is neatly contained in one cell or awkwardly split across several, which in turn changes the information carried by each local sample. By exposing grid offset as a first-class parameter, GridSamp gives experimenters systematic control over sampling density and the spatial arrangement of local samples — the two dimensions along which local-versus-global trade-offs are typically manipulated.

The toolbox also provides an unusually rich set of options for manipulating the appearance and arrangement of sampled regions once they have been extracted. Users can alter region shape and size, and they can swap or shuffle regions within the grid. These operations are the workhorses of a long tradition in perceptual psychology: shuffling the locations of image regions while preserving their local content disrupts global structure, allowing researchers to dissociate what is seen from where it is seen. Such manipulations tap directly into questions rooted in Gestalt psychology and the perception of hierarchical structure — whether local elements or global configuration dominate perception — and they underpin experimental paradigms ranging from studies of scene perception and eye movement guidance to neuroimaging work on how cortex responds to natural scene structure.

Extraction, too, is more flexible than simple cropping. GridSamp can pull regions out of an image either with or without their surrounding context, and it can return them in two distinct formats: as regions of interest, useful for analyses that treat each sample as an individual stimulus or measurement unit, and as reassembled mosaic images, useful when the experimental stimulus is the rearranged whole. The distinction between context-free and context-including extraction is scientifically meaningful in its own right. Studies of peripheral scene processing and contextual feedback in early visual cortex have shown that the same patch of pixels can be perceived differently — and can drive different neural responses — depending on the scene information that surrounds it. A toolbox that lets researchers toggle that context parametrically turns a subtle confound into a manipulable variable.

To demonstrate that the toolbox can faithfully recreate the materials of real experiments, the authors used GridSamp to reproduce stimuli from previous published studies across vision science. This kind of demonstration serves a dual purpose. Practically, it shows that the toolbox is expressive enough to cover the diversity of grid-based designs already in the literature, from simple tiling to more elaborate regional manipulations. Scientifically, it models the practice the toolbox is designed to encourage: researchers reproducing stimuli not by squinting at published figures and reverse-engineering code, but by running a documented, parameterized pipeline that anyone can inspect. The paper illustrates how the toolbox facilitates transparent and reproducible stimulus generation, positioning stimulus creation itself as something that can be archived, versioned, and verified rather than reconstructed from memory.

GridSamp is built on Python and requires Python 3.8 or higher. Under the hood it depends on a well-established stack of scientific Python libraries: Pillow for image input and output, NumPy for array manipulation, matplotlib for visualization, SciPy for scientific computing utilities, and scikit-image (skimage) for image processing operations, alongside Python’s base random and copy modules. That choice of foundation is deliberate and strategic. These are the libraries that vision scientists and computational researchers already use daily, so integrating grid sampling into an existing analysis pipeline requires no new infrastructure. The toolbox is distributed through the Python Package Index, meaning it can be installed with a single pip command, and the full source code, together with interactive Jupyter Notebook tutorials, is freely available on GitHub. The tutorials deserve particular emphasis: they lower the entry barrier for students and newcomers who might otherwise be intimidated by writing image-manipulation code from scratch, which is precisely the accessibility gap the authors set out to close.

The range of research programs that stand to benefit is broad. In scene perception, grid sampling has been used to probe how local image regions guide fixation, how scene summary statistics support object recognition, and how semantic meaning and low-level features compete to direct attention — a topic that remains actively debated in the literature on meaning maps and saliency models. In empirical aesthetics, researchers have examined whether the beauty of an image can be predicted from the perceptual and integrative properties of its parts, and whether viewers’ inspection is drawn to details that carry aesthetic weight. In computer vision and machine learning, grid-based decomposition lies at the heart of self-supervised learning approaches, most famously jigsaw-puzzle methods in which networks learn visual representations by predicting how shuffled image patches fit back together. Even research on change detection, visual search anchored on scene objects, and sensitivity to the visual field origin of image patches has relied on systematically sampled regions. For all of these communities, a shared, well-documented tool changes the economics of doing rigorous stimulus control.

The initiative also fits into a wider movement within psychology and neuroscience toward methodological toolboxes that standardize specific, error-prone steps of the experimental workflow. Precedents include tools for controlling low-level image properties so that stimuli are matched in luminance and contrast across conditions, and recent pedagogical work consolidating best practices for working with areas of interest in eye tracking. Grid sampling had remained an outlier: ubiquitous in practice yet unstandardized in code. By giving it a canonical implementation, GridSamp effectively raises the floor for the field. Reviewers can ask not only whether a study used a grid, but which grid parameters, and authors can answer with a software citation and a configuration file instead of a verbal approximation.

For the Leuven group, the toolbox emerges from an active research program on scene perception, meaning maps, and empirical aesthetics, and the development was supported by a PhD fellowship from Research Foundation – Flanders (FWO) awarded to Leemans and by long-term structural funding from the Flemish government awarded to Wagemans. The software is openly available, and the authors report no conflicts of interest. What began as an internal solution to a recurring stimulus-generation bottleneck has been generalized into infrastructure that any laboratory can adopt. In a field where the difference between a replicated finding and a failed one can hinge on a one-cell offset in a grid, that kind of precision — packaged in an installable module with tutorials to match — is the sort of unglamorous but consequential contribution on which cumulative science quietly depends. GridSamp turns a ubiquitous folk method into a standard, and in doing so makes the humble image grid a more trustworthy instrument for probing how the visual system builds wholes from parts.