--- a
+++ b/docs/pipeline/pipeline.md
@@ -0,0 +1,136 @@
+# Pipeline Details
+
+
+This section describes the HippUnfold workflow, that is, 
+the steps taken to produce the intermediate and final files.
+HippUnfold is a Snakemake workflow, and thus the workflow is a 
+ directed acyclic graph (DAG) that is automatically configured based
+on a set of rules. 
+
+## Overall workflow
+
+Below is a example *simplified* visualization of the workflow DAG
+for the `--modality T1w` workflow.  Each rounded rectangle in the DAG 
+represents a *rule*, that is, some code or script that produces 
+output file(s), and the arrows represent file inputs and outputs to these 
+rules.  It is *simplified* in that multiple 
+instances of each rule are not shown, e.g. the `run_inference` rule 
+runs on both left and right hemispheres (`hemi=L`, `hemi=R`),
+but only one `run_inference` box is shown here.  
+
+<img src="../../hippunfold/dags/out_rulegraph/T1w.png" width="800px">
+
+Although it may still look very complex (click on the image to 
+enlarge), it is also  organized into groups of rules, 
+each representing the main phases of the workflow. Each
+grouped set of rules also exist in separate rule files,
+ which can be found in
+ the [rules sub-folder](http://github.com/khanlab/hippunfold/tree/master/hippunfold/workflow/rules)  
+in the workflow source. For example, the [preproc_t1](http://github.com/khanlab/hippunfold/tree/master/hippunfold/workflow/rules/preproc_t1.smk)  file contains the rules related to pre-processing the T1w images, and these are 
+grouped together in the above diagram by a blue rectangle labelled `preproc_t1`. 
+
+
+The main phases of the workflow are described in the sections below, zooming in
+on the rules used in each blue rectangle, one at a time.
+
+
+## Pre-processing
+
+The pre-processing workflow for HippUnfold is generated based on the input data (e.g. whether 
+there are multiple T2w images or a single T2w image), what modality is used
+ (e.g. `--modality T1w` or `--modality T2w`), and what optional arguments are
+ specified (e.g. `--t1-reg-template`). 
+
+### T1w pre-processing
+
+T1w images are imported, intensity-corrected using N4, and linearly registered 
+to the template image (default: CITI168 - an HCP T1w template). An existing transformation to 
+align the images in a coronal oblique (`space-corobl`) orientation is concatenated, and 
+this space is used to define the left and right hippocampus bounding boxes in 0.3mm isotropic space. The left 
+hippocampus subvolume is left-right flipped at this stage too (subsequent steps in the `corobl` space operate
+on both the `hemi-R` and `hemi-Lflip` images).
+
+![T1w workflow preproc t1](../../hippunfold/dags/out_dag/T1w.preproc_t1.png)
+
+
+### T2w pre-processing
+
+T2w images are processed similarly, except the T2w version of the template is used. If multiple T2w images
+exist, these are motion-corrected and averaged prior to N4 correction. The diagram below shows the T2w pre-
+processing workflow for a dataset with three T2w runs.
+
+![T2w multi preproc_t2](../../hippunfold/dags/out_dag/T2w_multi.preproc_t2.png)
+
+### T2w with T1w template registration
+
+For T2w images where template registration is failing (e.g. because the T2w images have a limited FOV),
+the `--t1-reg-template` option can be used, and will perform template registration with the T1w images, along with 
+a within-subject registration of the T2w to the T1w, concatenating all the transforms. This is shown in the diagrams below (with a single T2w image in this case):
+
+![T2w t1-reg-template preproc_t1](../../hippunfold/dags/out_dag/T2w_t1-reg-template.preproc_t1.png)
+
+![T2w t1-reg-template preproc_t2](../../hippunfold/dags/out_dag/T2w_t1-reg-template.preproc_t2.png)
+
+Note that these are not the only workflow configurations possible, several other variants exist by using the command-line flags. For example, if you have T1w and T2w images that are already pre-processed and co-registered (e.g. HCP processed data), then you should use the `--skip-preproc` and `--skip-coreg` options to skip N4 and T1w/T2w co-registration.
+
+## U-net segmentation
+
+The U-net segmentation is performed on the cropped, `space-corobl` images, producing tissue segmentations (gray matter, SRLM, and anatomical landmarks for unfolding). This step is done in a single rule, which runs inference on the image using the corresponding
+nnU-net model based on the `modality` chosen. This is done on the `R` and `Lflip` hippocampus images, and the `Lflip` is subsequently unflipped. 
+
+![U-net workflow](../../hippunfold/dags/out_dag/T1w.nnunet.png)
+
+
+## Template-based shape injection
+
+Since the nnU-net segmentation may possibly contain topological errors that can cause issues when the Laplace-based coordinates, we perform an additional registration-based correction step, a shape injection, where we perform non-linear registration of a template hippocampus segmentation and the U-net segmentation, to warp the template shape. Regularization from the registration ensures topology from the template is preserved while it is warped to match the subject hippocampus. In addition to the segmentation, we also propagate Laplace coordinates to serve as an initialization to the next step.
+
+The following diagram shows the workflow, but simplified to contain one hemisphere (`--hemi R`), and excluding the dentate gyrus.
+
+![Shape injection](../../hippunfold/dags/out_dag/T1w_hemi-R_hipponly.shape_inject.png)
+
+
+## Laplace & equivolume coordinates
+
+The basis of the hippocampal unfolding is the definition of the Laplace coordinates. Here, Laplace's equation is solved on the domain of the gray matter, using the anatomical landmarks to define boundary conditions. This provides the intrinsic set of anatomical coordinates (AP, PD, IO) for unfolding the hippocampus. For the IO (laminar) coordinates we make use of the equivolume solution instead of Laplace.
+
+The following diagram shows the workflow, but simplified to contain one hemisphere (`--hemi R`), and excluding the dentate gyrus.
+
+![Laplace coordinates](../../hippunfold/dags/out_dag/T1w_hemi-R_hipponly.autotop.png)
+
+## Subfields processing
+
+The volumetric subfield segmentation is derived from the coord images from the last step, along with the atlas that defines how the coordinates map to subfields. 
+
+The following diagram shows the workflow, but simplified to contain one hemisphere (`--hemi R`), and excluding the dentate gyrus.
+
+![Subfields](../../hippunfold/dags/out_dag/T1w_hemi-R_hipponly.subfields.png)
+
+
+## Generating warp files
+
+To allow users to transform data between the different spaces, we generate warp files that can be applied to transform volumes of surfaces to and from the native and unfolded spaces.
+
+The following diagram shows the workflow, but simplified to contain one hemisphere (`--hemi R`), and excluding the dentate gyrus.
+
+![Generating warps](../../hippunfold/dags/out_dag/T1w_hemi-R_hipponly.warps.png)
+
+## Surface processing
+
+Using the warps, we transform standard template unfolded meshes to each subject hippocampus, in order to obtain surface meshes in the native space. These are stored in GIFTI format, and we also produce metric files to quantify surface morphometry (thickness, gyrification, curvature).  
+
+The following diagram shows the workflow, but simplified to contain one hemisphere (`--hemi R`), and excluding the dentate gyrus.
+
+![Surface processing](../../hippunfold/dags/out_dag/T1w_hemi-R_hipponly.gifti.png)
+
+
+## Additional steps
+
+Resampling to output resolution, quality control snapshot generation, and archiving the work folder are steps 
+that are also carried out by the workflow, but the DAGs are now shown here because of the many inputs/outputs, and 
+generally have straightforward workflow structures.
+
+
+
+
+