##############################################################
README.txt -- instructions for running mmap (Mac)
##############################################################

Quickstart

  [install XQuartz]
  [double-click SelfUnpackMappingMac.zip]
  % [next in xterm]
  % cd SelfUnpackMappingMac
  % ./mmap rotdil32
  fn-F1    # start
  fn-F2    # reset to wait
  Esc      # kill (else stim runs forever)

These are notes for running the self-unpacking version of my stimulus
program, mmap.  It runs the following set of included scripts.  By
making a copy of any script (HOWTO see below), you can modify any
of the parameters in the script (as well as several hundred not
explicitly listed) and then run the modified script.

  pol1       -- color checkerboard wedge, anti-clockwise
  pol2       -- color checkerboard wedge, clockwise
  pollet1    -- pol1 + monitor for numbers amongst letters
  pollet2    -- pol2 + monitor for numbers amongst letters
  polletdil1 -- pollet1 + masked dot motion fields
  polletdil2 -- pollet2 + masked dot motion fields
  ecc1       -- color checkerboard ring, expanding
  ecc2       -- color checkerboard ring, contracting
  ecclet1    -- ecc1 + monitor for numbers amongst letters
  ecclet2    -- ecc2 + monitor for numbers amongst letters
  eccletdil1 -- ecclet1 + masked dot motion fields
  eccletdil2 -- ecclet2 + masked dot motion fields
  lcms32     -- low contrast moving stationary, 16sec ON, 16sec OFF
  lcms32b    -- same but start stationary/OFF
  rotdil32   -- V6 optical flow localizer, 16sec ON, 16sec OFF
  rotdil32b  -- same, but start scrambled/OFF

This has been tested on Mac OS X 10.6.8 up to 10.15.4

N.B.: it requires that XQuartz.app is installed.

You should be able to run mmap directly without installing anything
else since it's all contained within the single mmap file.

First download the file, SelfUnpackMappingMac.zip, and then
double-click it, or command-line-unzip it as follows:

  unzip SelfUnpackMappingMac.zip

This should unzip a directory containing a single, executable file,
mmap, and NOTES.txt (this help file).

Now start up XQuartz and wait for an xterm to pop up.  Use 'cd' in
the xterm to change into the unzipped SelfUnpackMappingMac directory
that contains the file mmap.

You can move the mmap file to any directory and run it from anywhere.
Typing just ./mmap should respond:

---------------------------------------------
use: mmap <script> [usb]     (usb: Mac-only)
start=fn-F1 reset=fn-F2 quit=Esc
scripts:
  pol1
  pol2
  pollet1
  pollet2
  polletdil1
  polletdil2
  ecc1
  ecc2
  ecclet1
  ecclet2
  eccletdil1
  eccletdil2
  lcms32
  lcms32b
  rotdil32
  rotdil32b
---------------------------------------------

Finally, to run the various stimuli with default parameters, type:

  ./mmap pol1
  ./mmap pol2
  ./mmap pollet1
  ./mmap pollet2
  ... [etc]

The initial '.' is to make sure you are using the mmap in the current
directory.  In the (unlikely) event you have a DIO-USB-32 USB<->TTL
box, you can also add the "usb" argument (loads firmware into this
box to set it up for 32 bits of TTL I/O via USB).  This doesn't (yet)
work on the very latest MacOS (worked until 10.14 I think).

This should start mmap to a "Ready" screen.  Here are the hot keys
to control it:

  Esc -> kill
  F1  -> start immediately
  F2  -> go back to "Ready"

Every time it runs, mmap will dump out the script it is using to
the terminal.  To capture the script to a file, do something like
this:

  ./mmap pol1 > pol1-modified

Then modify the parameters in "pol1-modified".  When dumping out a
copy of the default script, you can choose any name for the output
filename *except* the original script filename.  That is, *don't*
do:

  ./mmap pol1 > pol1

because the shell will delete the default pol1 script it is trying
to read before mmap gets a chance to read it :-}

To run the modified script, simply do:

  ./mmap pol1-modified

If mmap finds "pol1-modified" in the current directory, it will use
the parameters in that script instead of the default ones.  That
way, you can change any parameter you want (you can also add
parameters not listed).

If you somehow mess up editing the modified script and mmap won't
start with the modified script, you can always just dump out a new
default one with:

  ./mmap pol1 > pol1-modified

Here are some examples of how to modify parameters.

The default stimulus window size is XGA, which is 1024x768 pixels
(the remainder of the display will be black).  To change the size
of stimulus window, find the in in the default script that looks
like this:

----------------------------
...
  -winxy $STIMWINX $STIMWINY \
...
----------------------------

and change it -- for example, if you want to get HDMI --
to this:

----------------------------
...
  -winxy 1920 1080 \
...
----------------------------

To cause mmap to wait for a certain number of presses of a USB
keyboard '5' key to start, start with the default script which
should end with:

----------------------------
...
...
   -waitforpulse $PULSECNT \
   $@ &
----------------------------

Currently, it is being passed -1 for PULSECNT, which means, just
wait for the F1 key.  Change this to something like:

----------------------------
...
...
   -waitforpulse 9 \
   -fivekeytrigger \
   $@ &
----------------------------

When you start mmap now, you will get a "Ready" screen as before,
but the stim will start on the 9th hit of the '5' key (if, for
example, you have a scanner pulse trigger that can generate USB
keyboard '5' keystrokes, and it is plugged into a USB port on the
stimulus computer).

Alternatively, you can trigger the stimulus with the apostrophe key
(single-quote) as follows:

----------------------------
...
...
   -waitforpulse 9 \
   -apostrophetrigger \
   $@ &
----------------------------

To save tiff frames of any stimulus at any desired frame rate
add the following options.  Example below saves frames at 60 Hz
for 4 seconds (240 frames) starting from 12 seconds into the
stimulus to the output directory /tmp:

----------------------------
...
...
   -saveframes 60 180 \
   -firstframetime 12.0 \
   -tiffoutdir /tmp
   $@ &
----------------------------

If you want a timestamped log of 0-9 USB key presses, and stimulus
events, resets, etc, make sure this line is present in the script
file:

  -logfile \

This will dump a log into the current directory every time the
stimulus is run, creating a file using a filename that has a timestamp
and the stimulus type in it:

  YYMMDD-HHMMSS_<stimtype>.log

for example:

  161128-151939_rotdil0.log 

To stop mmap from dumping a logfile, change the line to:

  -nologfile \

Each parameter in the script is on its own backslashed (continuation)
line for ease of reading.  Make sure there are no stray spaces after
any backslash (which cancels the continuation effect).

If a parameter appears twice, the last value of it is used.  That
way, you can leave the default values in there for reference.

Since the mmap program reads the unix microsecond clock every new
video frame to determine what to draw, you may want to temporarily
turn off setting the data and time automatically from the internet
as follows:

  System Preferences -> Date and Time ->

    [unlock panel at lower left using admin passwd]
    untick "Set data and time automatically:"

cheers,
marty sereno
msereno@sdsu.edu

