##############################################################
NOTES.txt -- instructions for running mmap (64-bit Linux)
##############################################################

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 CentOS 5.9 and Ubuntu 16.04.  On
Ubuntu 16.04, it may require installing the shared library,
libjpeg62, if it is not installed.  On Ubuntu 16.04, that
library should be located here:

  /usr/lib/x86_64-linux-gnu/libjpeg.so.62

If it's not there on your machine, download the .deb file
for libjpeg62 from:

  https://packages.ubuntu.com/xenial/amd64/libjpeg62/download

and install it as follows:

  sudo dpkg -i libjpeg62_6b2-2_amd64.deb

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

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

  unzip SelfUnpackMappingLinux64.zip

This should unzip a directory containing a single,
executable file, mmap, and NOTES.txt (this help).  You can
move the mmap file to any directory.  Now use 'cd' to
change into the directory where mmap is. 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 (ignore the "usb" argument, which is
Mac-only -- it loads firmware onto a DIO-USB-32 USB<->TTL
box).

This will 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 \
   $@ &
----------------------------

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 frame to determine what to draw, you may want to
temporarily suspend automatic time updates by the network
time daemon, ntpd, using a command like the following
(depends on OS version):

  sudo service ntpd stop

You can turn it back on with:

  sudo service ntpd start

cheers,
marty sereno
msereno@sdsu.edu

