___________________________________________________________________________
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.
- The RGC layer is now enabled by default (pars.rgc.enabled = 1), using a
   new default mode, pars.rgc.mode = 'derivative': 4 channels, one per
   temporal-derivative order (0-3), each with a single-pixel spatial RF.
   This reconstructs legacy V1/MT responses essentially exactly, with no
   weight fitting required, and gives a clean 4-channel substrate for
   lesion studies via pars.rgc.derivative.channelGain. The original
   biological four-population model (ON/OFF x fast/slow, with fitted
   weights) remains available as pars.rgc.mode = 'fourPop'.
- 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) RGC front-end (enabled by default):

   pars = shPars;   % pars.rgc.enabled == 1, pars.rgc.mode == 'derivative'

   By default the stimulus passes through an RGC layer before reaching V1,
   using the 'derivative' mode: 4 channels, one per temporal-derivative
   order (0-3) of the same kernel family V1's temporal filters use, each
   with a single-pixel spatial RF (no spatial filtering at the RGC stage).
   This reconstructs legacy V1/MT responses essentially exactly -- no
   weight fitting is required. To lesion a channel:

   pars.rgc.derivative.channelGain(2) = 0;  % silence the order-1 channel

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

   A second, biological RGC mode is also available:

   pars = shPars;
   pars.rgc.mode = 'fourPop';
   pars.rgc.v1Weights = [];

   This is the original four-population model, with 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. 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;

4) First-pass RGC calibration protocol (fourPop mode only):

   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