README on BinocularDisplayChecker

Created : "2016-01-17 14:57:53 ban"
Last Update: "2021-12-13 07:28:12 ban"

---

BinocularDisplayChecker -- Left/right-eye image position adjustment tool for neuroimaging/psychophysics experiments

This MATLAB tool generates a series of wallpapers with some guidelines shown in the illustration.
In neuroimaging and psychophysics experiments, when we are going to use some binocular visual stimulus (e.g. stereograms, or binocular rivalry), we may have to present left- and right-eye images onto two independent displays/projectors separately (and we may further use an additional display for a console). In such a situation, a strict adjustment of the two display projection positions will be necessary for accurate binocular fusion and precise measurements. To this end, some background wallpaper image with which we can easily detect displacement by visual inspection is required. The wallpaper(s) generated by this tool can support these corrections by presenting guidelines/rulers on the screen.

For generating guideline wallpapers, this toolbox provides two different ways as below.

1. The images with the required size are first generated by a MATLAB function, and then the wallpapers are drawn by combining these images. Please use GenerateBinocularWallpaperGen for this method. Psychtoolbox is required.

2. The pre-existing PNG images (stored in ~/BinocularDisplayChecker/pngs/) are copied and combined to make the required wall papers. You can use GenerateBinocularWallpaperCopy for this method.

   Here, this second procedure is easier and simpler, while it may not be user friendly; only limited pairs of display resolutions can be accepted since pre-existing images with fixed image sizes are just copied and combined. However, I still keep and prefer this second procedure as we can embed outlined polished texts on the images by using the Adobe Illustrator's font drawing functionality.

For the pragmatic purpose, there would be no difference between these two procedures. Please select one based on your own preference.

examples

>> GenerateBinocularWallpaperGen([1920,1200;1920,1080;1920,1080],[127,127,127]);
>> GenerateBinocularWallpaperGen([0,0;1920,1080;1920,1080],[127,127,127]);
>> GenerateBinocularWallpaperCopy([1920,1200;1920,1080;1920,1080],[127,127,127]);
>> GenerateBinocularWallpaperCopy([0,0;1920,1080;1920,1080],[127,127,127]);

usage

function GenerateBinocularWallpaperGen(ress,:bgcolor)
function GenerateBinocularWallpaperCopy(ress,:bgcolor)
(: is optional)

input (common between the two main functions)

ress: display resolutions, a 3 x 2 matrix.
      [width_display_1, height_display_1; width_display_2, height_display_2; width_display_3, height_display_3]
      here, display 1 is for a console, display 2 is for presenting left-eye image, and display 2 is for
      presenting right-eye image.
      e.g. ress=[1920,1200; 1920, 1080; 1920, 1080].

      NOTE 1: if you don't use the console display (display 1) or the right-eye-image (display 3),
              please set 0 to ress of these displays.
              e.g. ress=[0,0; 1920, 1080; 1920, 1080]; or ress=[0,0;0,0;1920,1080];

      NOTE 2: currently, only specific pairs of the display resolutions listed below are available
              since the images are prepared in advance. if you need different resolutions, please generate
              PNG wallpaper materials in advance using some graphics software.
              available: [1024, 768], [1280,1024], [1920,1080], [1920,1200], and [2560, 1440] (width,height).
bgcolor : (optional) background to be used on the console display (display 1)
          bgcolor=[127,127,127] by default.

output (common between the two main functions)

no output variable, the generated wallpaper image is saved in
the current directory as wallpaper_[1|2|3]_display*.png

NOTE

Some other images, which can be used for testing whether the binocular display
setups are done properly, are also provided with this tool. You can find them in
~/BinocularDisplayChecker/stereo_checker.

License

BinocularDisplayChecker -- Left/right-eye image position adjustment tool for neuroimaging/psychophysics experiments. Copyright (c) 2016, Hiroshi Ban. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in
  the documentation and/or other materials provided with the distribution

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of the FreeBSD Project.