___________________________________________________________________________
DECRIPTION

This package contains a MatLab implementation of a model for cortical
neurons in visual area MT, as described in detail in the references
given at the bottom of this document.  The model takes as input a
discretized visual stimulus sequence (movie), and computes firing rate
responses of two successive neural populations, corresponding to
direction-selective complex cells in visual area V1, and
"pattern-selective" neurons in area MT.  Further information, as well
the most recent versions of the code, are available at

    http://www.cns.nyu.edu/~lcv/MT-model.html

Project planning note:

- See AGENTS.md at repository root for the active RGC front-end roadmap,
  implementation status, and next execution steps.

Recent major updates:

- Native MATLAB fallbacks were added for core 3D operations used by the
   model internals, reducing dependence on legacy precompiled MEX binaries.
- The V1 linear stage now uses explicit native helper calls for blur and
   valid correlation steps.
- Gaussian blur internals were updated to call native helper functions,
   preserving the separable filtering pipeline while improving portability.
- An optional retinal ganglion cell (RGC) preprocessing layer was added in
   front of V1. By default it is disabled so legacy behavior is preserved.
- The RGC layer was expanded to four populations (ON/OFF x fast/slow) and
   then to eight by adding optional lagged (temporally phase-shifted) copies
   of each channel, controlled by pars.rgc.temporal.fastLag and slowLag.
- The V1 spatial projection stage was corrected to apply all 10 spatial
   derivative combinations (spatial orders 0-3, matching shModelV1Linear's
   full spatiotemporal basis) rather than only the 4 third-order combinations.
   Each RGC channel output (a 2D neural image) is now projected onto the full
   V1 spatial derivative set, so V1 neurons perform weighted sums over the
   spatial map of RGC outputs rather than over a fixed set of scalar features.
- A parameter sweep tool (shSweepRgcTemporalPars) was added to find the RGC
   temporal parameters that maximise V1 correlation with the legacy model.
- A calibration helper was added to fit healthy RGC parameters so V1/MT
   outputs stay close to the legacy model before impairment is introduced.
- Legacy C/MEX sources are still included in the repository for reference.

Authors:  Timothy Saint and Eero P. Simoncelli
___________________________________________________________________________
INSTALLATION

1) Download and unpack the folder containing the code.  You can put
   the folder anywhere on your system, but we'll assume it's in a
   folder/directory named "MTmodel".

2) No MEX compilation is required for normal use. The core model now runs
   with native MATLAB implementations.

   Optional: Legacy C/MEX sources are still included in the mex subfolder
   for reference and experimentation. Core model internals call explicit
   native helper functions, so default execution does not depend on MEX.

3) Optional RGC front-end (default OFF):

   pars = shPars;
   pars.rgc.enabled = 1;

   With RGC enabled, the stimulus passes through a population of model
   retinal ganglion cells before reaching V1.  The RGC layer has four base
   channel classes (onFast, offFast, onSlow, offSlow) defined by polarity
   (ON/OFF center-surround) and temporal speed (fast/slow biphasic kernel).
   Each channel is a 2D neural image -- the full spatial array of RGC
   responses for that class -- with the same spatial layout as the stimulus.

   Optional lagged channels (temporal phase offset) can be enabled:

   pars.rgc.temporal.fastLag = 1;  % frames; 0 = disabled (default)
   pars.rgc.temporal.slowLag = 2;  % frames; 0 = disabled (default)

   With both lags enabled the layer has 8 channel classes.

   At the V1 stage each RGC neural image is projected onto all 10 spatial
   derivative combinations (xorder+yorder from 0 to 3), matching the full
   spatiotemporal basis of shModelV1Linear.  V1 neurons therefore perform
   weighted sums over the spatial map of RGC outputs, which is the mechanism
   by which orientation and direction selectivity arise.

   Before use, fit per-neuron V1 weights with:

   pars.rgc.v1Weights = shFitRgcV1Weights(pars, stimulusSet);

   or run the parameter sweep to find temporal parameters and fit weights:

   results = shSweepRgcTemporalPars;
   pars    = results.bestPars;

   Set pars.rgc.enabled = 0 to revert to the original no-RGC model.

4) First-pass RGC calibration protocol:

   report = shCalibrateRgcLayer;

   This fits healthy RGC parameters to keep V1/MT outputs close to the
   legacy model with RGC disabled.

___________________________________________________________________________
USING THE SOFTWARE

0) Start matlab, and put the MTmodel folder in your path:

   addpath(genpath('PATHNAME-OF-MTmodel'));

1) Start by going through the shTutorial1.m file in the "tut"
   folder.  This will show you how to compute responses of various
   stages of the model to any stimulus, and how to generate tuning
   curves.

2) Over time, we will be releasing extensions to the model, as well as 
   addition demonstrations and tutorials.  Check back at
        http://www.cns.nyu.edu/~lcv/MT-model.html
   for current status.

___________________________________________________________________________
REFERENCES

E P Simoncelli and D J Heeger.  A Model of Neuronal Responses in
  Visual Area MT.  Vision Research, 38(5):743-761, March 1998.     
  [Full journal article, with model details]
  http://www.cns.nyu.edu/~eero/ABSTRACTS/simoncelli96-abstract.html

E P Simoncelli, W D Bair, J R Cavanaugh, and J A Movshon. Testing and
  Refining a Computational Model of Neural Responses in Area MT.
  ARVO, 1996.
  [Conference presentation and abstract on testing predictions of the 
   model regarding bimodality of grating direction-tuning curves at
   slow speeds.  Slides available online]
  http://www.cns.nyu.edu/~eero/ABSTRACTS/ARVO-abstracts.html

D J Heeger, E P Simoncelli, and J A Movshon.
   Computational Models of Cortical Visual Processing.
   Proc. National Academy of Science. 93:623-627. January, 1996.
   [Brief description of V1 and MT models]
   http://www.cns.nyu.edu/~eero/ABSTRACTS/pnas95-abstract.html

E P Simoncelli and D J Heeger.
   A velocity-representation model for MT cells. ARVO, 1994.
   [Early conference presentation  and abstract.  Slides available online]
   http://www.cns.nyu.edu/~eero/ABSTRACTS/ARVO-abstracts.html

Eero P Simoncelli. Distributed Analysis and Representation of Visual Motion.
   PhD thesis, Massachusetts Institute of Technology, Department of
   Electrical Engineering and Computer Science, Cambridge MA, January 1993.
   [Original version of the model, which did not include normalization 
    of the MT stage]  
   http://www.cis.upenn.edu/~eero/ABSTRACTS/simoncelli-phd-abstract.html