Package of forward-model code for 3d segmented tissue models
	------------------------------------------------------------

			Alex Barnett 4/12/02


tMCimg - Monte-carlo time-domain simulation, single-source, multiple-detector.
	 Handles reflections, non-unity refractive indices, cubical voxels
	 of arbitrary size, input of physical quantities in units of mm.

		Inputs:	file.cfg - config file, optical properties, etc.
				(see sample3.cfg for example).
			segmentation.bin (or .seg) - tissue structure.
	       Outputs:	file.his - histories of photons reaching detectors.
			file.2pt - optional fluence array (3+1 dims).
		Detailed help given if call with no arguments.

	Current version tMCimg6.c
	Libraries required: math.

	Authors : Alex Barnett modifed from Jon Stott modified from Dave Boas.

	example: 'cd demo; ../tMCimg incl'


tFDimg - Finite-difference diffusion equation time-domain simulation.
	 Simple forward-Euler timestepping, multiple sources and
	 detectors. Dirichlet and (crude) Robin boundary conditions.

		Inputs: same as tMCimg except multiple sources allowed,
			and detector directions are made use of.
	       Outputs:	file.sig - text file of output signals by source,
				detector, timegate. (Arbitrary normalization).
			file.2pt - optional fluence array (3+1 dims).
		Detailed help given if call with no arguments.

	Current version tFDimg.c
	Libraries required: math, blas, lapack.

	Author : Alex Barnett.

	example: 'cd demo; ../tFDimg rc 0.05 incl'

tmcv -	interactive 3d display of fluence array movie, tissue types,
	sources and detectors. Currently only displays real part (imaginary
	part not implemented).

		Inputs: file.cfg - reads config file for SD locations, etc
			segmentation.bin (or .seg) - for tissue types.
			file.2pt - reads fluence array.

	Libraries required: math, Mesa, GLUT.

	Author : Alex Barnett.

	examples: 'cd demo; tmcv incl' (displays MC fluence), or
		  'cd demo; tmcv incl FD' (displays FD fluence).

cfg2inp - converts .cfg into Boas-style .inp (bare numbers) file, very
	useful for then reading into eg matlab.

	Author : Jon Stott.

reseg - rescales (resamples) segmentation files, options to flip xyz <-> yxz
	ordering, to set outer boundary to air, and to chop out a cuboid.

	Author : Alex Barnett.

***
MATLAB calling scripts: physics_of_tissue.m, phys_*.m, will be documented
shortly.
***

---------------------------------------------------------------------------


			BUG / TO DO list (incomplete) 5/28/03

* parser:

Detectors should be checked for pointing _into_ (not out of) material,
so det_move in tFDimg doesn't fail.

Add default direction, NA, radius (applies to all following srcs or dets,
until changed).

Add checking for img_{xyz} falling outside the system dimensions.
(Currently it just seg faults).


* Monte-carlo:

integrate Jon + Alex's source,det moving routines. Make a separate utils.c
code chunk for shared routines, load_config, saving 2pt, etc. Then when
a 3rd method comes along, it's easier.

tMCimg causes small pumping effect from low to high mus regions, due to
finite distance travelled before tissue-type rechecked. Solve by correct
solution of intersections with tissue boundaries. This will be tMCimg7.

Allow srcdir = 0,0,0 for isotropic source (overrides NA?).

Change to correct definition of NA as sin of cone double-angle.

Allow parameter for maximum photon step to be other than 1 voxel size.

Validate non-unity refractive index effect on fluence equilibrium.

Correct detection of photons hitting air.

tMCimg doesn't handle multiple sources (need to modify .his format to .hiss
for this).

Add detector moving to boundary.

Bug in source radius: only selects from circle in xy plane, not rotated
correctly for source direction vector. Use 0 radius for now.


* Finite difference:

tFDimg-tMCimg validation incomplete for nonconstant-mus systems.

tFDimg should recode ADI using Douglas-Gunn scheme, and validate.
(low priority)

Boundary conditions.
     i) Robin BCs implement in forward Euler, Dirichlet in ADI, debug.
     i) could incorporate Greg Boverman's smooth interpolated
	surface-normals. (low priority).
and use for Robin (and Neumann, for mirrored wall testing) BCs.

Currently Robin bc (-r option) can give negative fluence at early time!

Optimize choice of timestepping: small explicit for first fraction of a ns,
followed by large implicit steps (Cholesky decomp would allow fast steps
for all source positions).

Investigate extraction of lowest matrix eigenvalues, for fast
source-independent approach.

If dt(FD) > dt(timegate), not all .2pt timesteps will have data in them.


* Graphic display:

tmcv help info update.

tmcv should output movies, with programmable fly-by. (yeah, right).


* General:

Documentation of usage in latex, output file formats.

Packaging of Matlab routines for data processing (eg signal extraction
from .his file).

Settle on xyz ordering throughout since less confusing.

-------------------------------------------------------------------------

Fixed bugs:

incorrect dependence for make of cfg2inp executable.

IN_ROI had swapped y-z.

cfg2inp outputs new .inp format with multiple sources.

tmcv array overrun bug fixed in colour planes of quads plot.

tmcv now has non-antialiased line display options.

tMCimg bugs in TISSUE_TYPE, replaced by GET_TISSUE, etc. Fixed bugs in IN_ROI,
etc.

tFDimg extract_sig failure to initialize det_sig[d] if ni[i][j][k]==-1.

check for srcdir or detdir = 0,0,0 (because FD needs both directions to
be valid).

New beam-based optode models, symmetric for S,D, better diagnosis.
(Reduced voxellated-boundary-dependent signal effects).

Wrong tissue type identified from tissue_penetrate to sparse_optode_vec, fixed!

If timegate narrower than dt, interpolation not correct (5/2/03). This
would get corrected when write new version with CNvar timestepping.
Fixed 5/28/03.