Merge pull request #225 from mlin865/intestines

Intestines

docs/index.rst

@@ -13,8 +13,10 @@ This documentation is intended to be a resource describing details about using i
    scaffolds/bladder
    scaffolds/brainstem
    scaffolds/colon
+   scaffolds/esophagus
    scaffolds/heart
    scaffolds/lung
+   scaffolds/smallintestine
    scaffolds/stomach
 
 

docs/scaffolds/esophagus.rst

@@ -0,0 +1,98 @@
+Esophagus Scaffold
+==================
+
+The current esophagus scaffold is ``3D Esophagus 1`` built from ``class MeshType_3d_esophagus1``.
+The human variant is shown in :numref:`fig-scaffoldmaker-human-esophagus`.
+
+.. _fig-scaffoldmaker-human-esophagus:
+
+.. figure:: ../_images/scaffoldmaker_human_esophagus.jpg
+   :align: center
+
+   Human esophagus scaffold.
+
+The esophagus scaffold is a 3-D volumetric model of the esophagus representing the cervical, thoracic and abdominal
+esophagus.
+
+Variants
+--------
+
+The esophagus scaffold is provided with parameter set only for human at this stage.
+
+This variant's geometry and annotations are best viewed in the **Scaffold Creator** tool in the ABI Mapping Tools.
+On the web, the latest published generic esophagus scaffold variant can be viewed on the
+`SPARC Portal <https://sparc.science/>`_ by searching for ``esophagus``, filtering for anatomical models, selecting a
+variant and viewing the scaffold in its Gallery tab or via the `Organ Scaffolds
+<https://docs.sparc.science/docs/organ-scaffolds>`_ help article.
+
+The esophagus scaffold script generates the scaffold mesh and geometry from ellipsoid and cubic functions based on a one
+dimensional central path which describes the path of the esophagus. The parameters were carefully tuned for the species,
+and it is not recommended that these be edited.
+
+Instructions for editing the central path are given with the ABI Mapping Tools **Scaffold Creator** documentation.
+Note that the D2 derivative along the path points towards the first node around the cross-section along the esophagus.
+If editing, use the Interactive Functions to *Smooth derivatives*, and *Smooth side cross derivatives* to make these as
+smooth as required.
+
+The central path used to generate the current human esophagus scaffold is obtained from tracing a central path from
+esophageal data retrieved from Anatomography.
+
+The mucosa, submucosa, circular muscle, longitudinal muscle and serosa layers of the esophagus are fully represented on
+the scaffold when *Number of elements through wall* is set to ``4``. Alternatively, the entire esophagus wall can be
+represented as a single layer by setting *Number of elements through wall* to ``1``.
+
+Coordinates
+-----------
+
+The esophagus scaffold defines the geometric, flat and material coordinates.
+
+The geometric ``coordinates`` field gives an approximate, idealized representation of the esophagus shape for the
+species, which is intended to be fitted to actual data for a specimen.
+
+The ``flat coordinates`` represents the geometric field when the esophagus scaffold is cut along its length and laid
+flat. This field is intended for fitting data obtained from a flat esophagus preparation.
+
+The material coordinates field ``esophagus coordinates`` defines a highly idealized coordinate system to give permanent
+locations for embedding structures in the esophagus. It is a cylindrical tube and can be viewed by visualising this
+field in the *Display* tab of **Scaffold Creator**.
+
+The esophagus scaffold supports limited refinement/resampling by checking *Refine* (set parameter to ``true``) with
+chosen *Refine number of elements* parameters. Be aware that only the ``coordinates`` field is currently defined on the
+refined mesh (but annotations are transferred).
+
+Annotations
+-----------
+
+Important anatomical regions of the esophagus are defined by groups of elements (or faces, edges and nodes/points) and
+annotated with standard term names and identifiers from a controlled vocabulary.
+
+Annotated 3-dimensional volume regions are defined by groups of 3-D elements including:
+
+* abdominal part of esophagus
+* cervical part of esophagus
+* esophagus
+* esophagus mucosa
+* esophagus smooth circular layer
+* esophagus smooth longitudinal layer
+* submucosa of esophagus
+* thoracic part of esophagus
+
+**Terms for volume regions such as the above are not to be used for digitized contours!** They are used for applying
+different material properties in models and the strain/curvature penalty (stiffness) parameters in fitting.
+
+Annotated 2-dimensional surface regions are defined for matching annotated contours digitized from medical images
+including (where ``surface`` is the outside boundary on the meshes):
+
+* luminal surface of esophagus
+* serosa of esophagus
+
+Annotated 1-dimensional line regions are defined for matching annotated contours digitized from medical images including
+(using only one of the items separated by slash /):
+
+* circular-longitudinal muscle interface of esophagus along the cut margin
+
+Several fiducial marker points are defined on the esophagus scaffold, of which the followings are potentially usable
+when digitizing:
+
+* distal point of lower esophageal sphincter serosa on the greater/lesser curvature of stomach
+* proximodorsal/ proximoventral midpoint on serosa of upper esophageal sphincter

docs/scaffolds/smallintestine.rst

@@ -0,0 +1,98 @@
+Small Intestine Scaffold
+========================
+
+The current small intestine scaffold is ``3D Small Intestine 1`` built from ``class MeshType_3d_smallintestine1``.
+The human variant is shown in :numref:`fig-scaffoldmaker-human-small-intestine`.
+
+.. _fig-scaffoldmaker-human-small-intestine:
+
+.. figure:: ../_images/scaffoldmaker_human_smallintestine.jpg
+   :align: center
+
+   Human small intestine scaffold.
+
+The small intestine scaffold is a 3-D volumetric model of the small intestine representing the duodenum, jejunum and
+ileum.
+
+Variants
+--------
+
+The small intestine scaffold is provided with parameter sets for the following three species:
+
+* Cattle
+* Human
+* Mouse
+
+These variants' geometry and annotations are best viewed in the **Scaffold Creator** tool in the ABI Mapping Tools.
+On the web, the latest published generic small intestine scaffold variants can be viewed on the
+`SPARC Portal <https://sparc.science/>`_ by searching for ``small intestine``, filtering for anatomical models,
+selecting a variant and viewing the scaffold in its Gallery tab or via the `Organ Scaffolds
+<https://docs.sparc.science/docs/organ-scaffolds>`_ help article.
+
+The small intestine scaffold script generates the scaffold mesh and geometry from ellipsoid and cubic functions based on
+a one dimensional central path which describes the path of the small intestine. The parameters were carefully tuned for
+each species, and it is not recommended that these be edited.
+
+Instructions for editing the central path are given with the ABI Mapping Tools **Scaffold Creator** documentation.
+Note that the D2 derivative along the path points towards the first node around the cross-section along the small
+intestine. If editing, use the Interactive Functions to *Smooth derivatives*, and *Smooth side cross derivatives* to
+make these as smooth as required.
+
+The central paths used to generate the current cattle and mouse small intestine scaffold are obtained from tracing
+central paths from dissection images and average dimensions obtained from the literature. The human small intestine
+scaffold is created based on a central path and data derived from the small intestine retrieved from Anatomography.
+
+The mucosa, submucosa, circular muscle, longitudinal muscle and serosa layers of the small intestine are fully
+represented on the scaffold when *Number of elements through wall* is set to ``4``. Alternatively, the entire small
+intestinal wall can be represented as a single layer by setting *Number of elements through wall* to ``1``.
+
+Coordinates
+-----------
+
+The small intestine scaffold defines the geometric, flat and material coordinates.
+
+The geometric ``coordinates`` field gives an approximate, idealized representation of the small intestine shape for the
+species, which is intended to be fitted to actual data for a specimen.
+
+The ``flat coordinates`` represents the geometric field when the small intestine scaffold is cut along its length and
+laid flat. This field is intended for fitting data obtained from a flat small intestine preparation.
+
+The material coordinates field ``small intestine coordinates`` defines a highly idealized coordinate system to give
+permanent locations for embedding structures in the small intestine. It is a cylindrical tube and can be viewed by
+visualising this field in the *Display* tab of **Scaffold Creator**.
+
+The small intestine scaffold supports limited refinement/resampling by checking *Refine* (set parameter to ``true``)
+with chosen *Refine number of elements* parameters. Be aware that only the ``coordinates`` field is currently defined on
+the refined mesh (but annotations are transferred).
+
+Annotations
+-----------
+
+Important anatomical regions of the small intestine are defined by groups of elements (or faces, edges and nodes/points)
+and annotated with standard term names and identifiers from a controlled vocabulary.
+
+Annotated 3-dimensional volume regions are defined by groups of 3-D elements including:
+
+* circular muscle layer of small intestine
+* duodenum
+* ileum
+* jejunum
+* longitudinal muscle layer of small intestine
+* mucosa of small intestine
+* small intestine
+* submucosa of small intestine
+
+**Terms for volume regions such as the above are not to be used for digitized contours!** They are used for applying
+different material properties in models and the strain/curvature penalty (stiffness) parameters in fitting.
+
+Annotated 2-dimensional surface regions are defined for matching annotated contours digitized from medical images
+including (where ``surface`` is the outside boundary on the meshes):
+
+* luminal surface of duodenum
+* serosa of duodenum
+* serosa of small intestine
+
+Annotated 1-dimensional line regions are defined for matching annotated contours digitized from medical images including
+(using only one of the items separated by slash /):
+
+* circular-longitudinal muscle interface of the first segment of the duodenum along the gastric-omentum attachment

docs/scaffolds/stomach.rst

@@ -53,15 +53,11 @@ coordinates definition (see below).]
 Coordinates
 -----------
 
-The stomach scaffold defines the geometric, split and material coordinates.
+The stomach scaffold defines the geometric and material coordinates.
 
 The geometric ``coordinates`` field gives an approximate, idealized representation of the stomach shape for the species,
 which is intended to be fitted to actual data for a specimen.
 
-The ``split coordinates`` follows the geometric field but provides disconnected and duplicated derivatives for nodes on
-the margin between the dorsal and ventral stomach (the boundary where stomach specimens are usually dissected into
-halves for imaging purposes). This field is intended for fitting data obtained from the dorsal or ventral stomach.
-
 The material coordinates field ``stomach coordinates`` defines a highly idealized coordinate system to give permanent
 locations for embedding structures in the stomach. It is defined by a capsule-shaped structure with an inlet cylindrical
 tube representing the esophagus and another outlet tube representing the duodenum. This can be viewed by

src/scaffoldmaker/annotation/cecum_terms.py

@@ -0,0 +1,20 @@
+"""
+Common resource for cecum annotation terms.
+"""
+
+# convention: preferred name, preferred id, followed by any other ids and alternative names
+cecum_terms = [
+    ("caecum", "UBERON:0001153", "FMA:14541", "ILX:0732270")
+    ]
+
+
+def get_cecum_term(name: str):
+    """
+    Find term by matching name to any identifier held for a term.
+    Raise exception if name not found.
+    :return ( preferred name, preferred id )
+    """
+    for term in cecum_terms:
+        if name in term:
+            return (term[0], term[1])
+    raise NameError("Cecum annotation term '" + name + "' not found.")

src/scaffoldmaker/annotation/colon_terms.py

@@ -6,16 +6,15 @@
 colon_terms = [
     ("ascending colon", "UBERON:0001156", "FMA:14545", "ILX:0734393"),
     ("descending colon", "UBERON:0001158", "FMA:14547", "ILX:0724444"),
-    ("caecum", "UBERON:0001153", "FMA:14541", "ILX:0732270"),
     ("circular muscle layer of colon", "ILX:0772428"),
     ("colon", "UBERON:0001155", "FMA:14543", "ILX:0736005"),
     ("colonic mucosa", "UBERON:0000317", "FMA:14984", "ILX:0731046"),
-    ("distal colon", "UBERON:0008971", "ILX:0727523"),
+    ("left colon", "UBERON:0008971", "ILX:0727523"),
     ("longitudinal muscle layer of colon", "ILX:0775554"),
     ("luminal surface of the colonic mucosa", "ILX:0793083"),
     ("mesenteric zone", "None"),
     ("non-mesenteric zone", "None"),
-    ("proximal colon", "UBERON:0008972", "ILX:0733240"),
+    ("right colon", "UBERON:0008972", "ILX:0733240"),
     ("serosa of colon", "UBERON:0003335", "FMA:14990", "ILX:0736932"),
     ("spiral colon", "UBERON:0010239", "ILX:0735018"),
     ("submucosa of colon", "UBERON:0003331", "FMA:14985", "ILX:0728041"),

src/scaffoldmaker/annotation/esophagus_terms.py

@@ -5,13 +5,15 @@
 # convention: preferred name, preferred id, followed by any other ids and alternative names
 esophagus_terms = [
     ("abdominal part of esophagus", "UBERON:0035177", "FMA:9397", "ILX:0735274"),
+    ("circular-longitudinal muscle interface of esophagus along the cut margin", "ILX:0793091"),
     ("cervical part of esophagus", "UBERON:0035450", "FMA:9395", "ILX:0734725"),
     ("distal point of lower esophageal sphincter serosa on the greater curvature of stomach", "ILX:0793179"),
     ("distal point of lower esophageal sphincter serosa on the lesser curvature of stomach", "ILX:0793180"),
     ("esophagus", "UBERON:0001043", "FMA:7131", "ILX:0735017"),
     ("esophagus mucosa", "UBERON:0002469", "FMA:62996", "ILX:0725079"),
     ("esophagus smooth muscle circular layer", "UBERON:0009960", "FMA:67605", "ILX:0727608"),
     ("esophagus smooth muscle longitudinal layer", "UBERON:0009961", "FMA:63573", "ILX:0735992"),
+    ("luminal surface of esophagus", "ILX:0793122"),
     ("proximodorsal midpoint on serosa of upper esophageal sphincter", "ILX:0793181"),
     ("proximoventral midpoint on serosa of upper esophageal sphincter", "ILX:0793182"),
     ("serosa of esophagus", "UBERON:0001975", "FMA:63057", "ILX:0725745"),

src/scaffoldmaker/annotation/smallintestine_terms.py

@@ -4,10 +4,18 @@
 
 # convention: preferred name, preferred id, followed by any other ids and alternative names
 smallintestine_terms = [
+    ("circular-longitudinal muscle interface of first segment of the duodenum along the gastric-omentum attachment", "ILX:0793090"),
+    ("circular muscle layer of small intestine", "ILX:0772669"),
     ("duodenum", "UBERON:0002114", "FMA:7206", "ILX:0726125"),
     ("ileum", "UBERON:0002116", "FMA:7208", "ILX:0728151"),
     ("jejunum", "UBERON:0002115", "FMA:7207", "ILX:0724224"),
-    ("small intestine", "UBERON:0002108", "FMA:7200", "ILX:0726770")
+    ("longitudinal muscle layer of small intestine", "ILX:0772125"),
+    ("luminal surface of duodenum", "ILX:0793121"),
+    ("mucosa of small intestine", "UBERON:0001204", "FMA:14933", "ILX:0770578"),
+    ("serosa of duodenum", "UBERON:0003336", "FMA:14948", "ILX:0732373"),
+    ("serosa of small intestine", "UBERON:0001206", "FMA:14938", "ILX:0727465"),
+    ("small intestine", "UBERON:0002108", "FMA:7200", "ILX:0726770"),
+    ("submucosa of small intestine", "UBERON:0001205", "FMA:14934", "ILX:0735609")
     ]
 
 

src/scaffoldmaker/annotation/stomach_terms.py

@@ -12,8 +12,6 @@
     ("circular muscle layer of stomach", "ILX:0774731"),
     ("circular-longitudinal muscle interface of body of stomach along the gastric-omentum attachment", "ILX:0793088"),
     ("circular-longitudinal muscle interface of dorsal stomach", "ILX:0793089"),
-    ("circular-longitudinal muscle interface of first segment of the duodenum along the gastric-omentum attachment", "ILX:0793090"),
-    ("circular-longitudinal muscle interface of esophagus along the cut margin", "ILX:0793091"),
     ("circular-longitudinal muscle interface of fundus of stomach along the greater curvature", "ILX:0793092"),
     ("circular-longitudinal muscle interface of gastroduodenal junction", "ILX:0793093"),
     ("circular-longitudinal muscle interface of pyloric antrum along the greater curvature", "ILX:0793135"),
@@ -25,18 +23,13 @@
     ("distal point of lower esophageal sphincter serosa on the greater curvature of stomach", "ILX:0793179"),
     ("distal point of lower esophageal sphincter serosa on the lesser curvature of stomach", "ILX:0793180"),
     ("dorsal stomach", "ILX:0793086"),
-    ("duodenum", "UBERON:0002114", " FMA:7206", "ILX:0726125"),
     ("esophagogastric junction", "UBERON:0007650", "FMA: 9434", "ILX:0733910"),
     ("esophagogastric junction along the greater curvature on circular-longitudinal muscle interface", "ILX:0793098"),
     ("esophagogastric junction along the greater curvature on luminal surface", "ILX:0793099"),
     ("esophagogastric junction along the greater curvature on serosa", "ILX:0793100"),
     ("esophagogastric junction along the lesser curvature on circular-longitudinal muscle interface", "ILX:0793101"),
     ("esophagogastric junction along the lesser curvature on luminal surface", "ILX:0793102"),
     ("esophagogastric junction along the lesser curvature on serosa", "ILX:0793103"),
-    ("esophagus", "UBERON:0001043", "FMA:7131", "ILX:0735017"),
-    ("esophagus mucosa", "UBERON:0002469", "FMA:62996", "ILX:0725079"),
-    ("esophagus smooth muscle circular layer", "UBERON:0009960", "FMA:67605", "ILX:0735992"),
-    ("esophagus smooth muscle longitudinal layer", "UBERON:0009961", "FMA:63573", "ILX:0727608"),
     ("forestomach-glandular stomach junction", "UBERON:0012270", "ILX:0729974"),
     ("fundus of stomach", "UBERON:0001160", " FMA:14559", "ILX:0724443"),
     ("fundus-body junction along the greater curvature on circular-longitudinal muscle interface", "ILX:0793104"),
@@ -60,8 +53,6 @@
     ("longitudinal muscle layer of stomach", "ILX:0772619"),
     ("luminal surface of body of stomach", "ILX:0793119"),
     ("luminal surface of cardia of stomach", "ILX:0793120"),
-    ("luminal surface of duodenum", "ILX:0793121"),
-    ("luminal surface of esophagus", "ILX:0793122"),
     ("luminal surface of fundus of stomach", "ILX:0793123"),
     ("luminal surface of pyloric antrum", "ILX:0793124"),
     ("luminal surface of pyloric canal", "ILX:0793125"),
@@ -71,16 +62,13 @@
     ("pyloric canal", "UBERON:0008858", "FMA:14580", "ILX:0735898"),
     ("serosa of body of stomach", "ILX:0771402"),
     ("serosa of cardia of stomach", "ILX:0776646"),
-    ("serosa of duodenum", "UBERON:0003336", "FMA:14948", "ILX:0732373"),
-    ("serosa of esophagus", "UBERON:0001975", "FMA:63057", "ILX:0725745"),
     ("serosa of fundus of stomach", "UBERON:0012503", "FMA:17073", "ILX:0726906"),
     ("serosa of pyloric antrum", "ILX:0777005"),
     ("serosa of pyloric canal", "ILX:0775898"),
     ("serosa of stomach", "UBERON:0001201", "FMA:14914", "ILX:0735818"),
     ("stomach", "UBERON:0000945", "FMA:7148", "ILX:0736697"),
-    ("submucosa of esophagus", "UBERON:0001972", "FMA:62997", "ILX:0728662"),
     ("submucosa of stomach", "UBERON:0001200", "FMA:14908", "ILX:0732950"),
-    ("ventral stomach", "ILX:0793085"),
+    ("ventral stomach", "ILX:0793085")
     ]
 
 

src/scaffoldmaker/meshtypes/meshtype_3d_bladderurethra1.py

@@ -874,7 +874,7 @@ def generateBaseMesh(cls, region, options):
         xWarpedList, d1WarpedList, d2WarpedList, d3WarpedUnitList = \
             tubemesh.warpSegmentPoints(innerNodes_x, innerNodes_d1, innerNodes_d2, segmentAxis, sxRefList, sd1RefList,
                                        sd2ProjectedListRef, elementsCountAround, elementsCountAlong,
-                                       zRefList, innerRadiusAlong, closedProximalEnd=True)
+                                       zRefList)
 
         if includeUrethra:
             wallThicknessList = [bladderWallThickness] * (elementsCountAlongBladder + 1) + [urethraWallThickness] * \