Adjust thresholds and add more docs

README.md

@@ -97,6 +97,24 @@ Copy input mask file to output directory.
 `--keep-mask` is a workaround for using `pl-fetal-surface-extract` as part of a
 _ChRIS_ pipeline. It eliminates the need for an extra _ts_ plugin step.
 
+#### `--distance-threshold`
+
+Set acceptable maximum distance error.
+
+Without subsampling, "sulci bridge" errors can happen.
+
+![Sulci bridge error](img/bridge_error.png)
+
+This error can be detected by large distance error. If distance error exceeds the distance threshold, then we rerun marching cubes with subsampling enabled.
+
+#### `--target-smoothness`
+
+Set target mean smoothness error.
+
+![Low quality surface](img/smoothness_error.png)
+
+The result of marching cubes, especially with subsampling enabled, can be poor quality. Taubin smoothing is applied to improve surface quality. The number of smoothing iterations is decided by the value for target smoothness.
+
 ## Local Usage
 
 To get started with local command-line usage, use [Apptainer](https://apptainer.org/)

extract_cp/__init__.py

@@ -4,10 +4,11 @@
 __version__ = __pkg.version
 
 DISPLAY_TITLE = r"""
-______   _        _   _____ ______   _____             __                 _____     _                  _   _             
-|  ___| | |      | | /  __ \| ___ \ /  ___|           / _|               |  ___|   | |                | | (_)            
-| |_ ___| |_ __ _| | | /  \/| |_/ / \ `--. _   _ _ __| |_ __ _  ___ ___  | |____  _| |_ _ __ __ _  ___| |_ _  ___  _ __  
-|  _/ _ \ __/ _` | | | |    |  __/   `--. \ | | | '__|  _/ _` |/ __/ _ \ |  __\ \/ / __| '__/ _` |/ __| __| |/ _ \| '_ \ 
-| ||  __/ || (_| | | | \__/\| |     /\__/ / |_| | |  | || (_| | (_|  __/ | |___>  <| |_| | | (_| | (__| |_| | (_) | | | |
-\_| \___|\__\__,_|_|  \____/\_|     \____/ \__,_|_|  |_| \__,_|\___\___| \____/_/\_\\__|_|  \__,_|\___|\__|_|\___/|_| |_|
+______   _        _   _____             __                 _____     _                  _   _             
+|  ___| | |      | | /  ___|           / _|               |  ___|   | |                | | (_)            
+| |_ ___| |_ __ _| | \ `--. _   _ _ __| |_ __ _  ___ ___  | |____  _| |_ _ __ __ _  ___| |_ _  ___  _ __  
+|  _/ _ \ __/ _` | |  `--. \ | | | '__|  _/ _` |/ __/ _ \ |  __\ \/ / __| '__/ _` |/ __| __| |/ _ \| '_ \ 
+| ||  __/ || (_| | | /\__/ / |_| | |  | || (_| | (_|  __/ | |___>  <| |_| | | (_| | (__| |_| | (_) | | | |
+\_| \___|\__\__,_|_| \____/ \__,_|_|  |_| \__,_|\___\___| \____/_/\_\\__|_|  \__,_|\___|\__|_|\___/|_| |_|
+                                                                                                          
 """

extract_cp/__main__.py

@@ -30,7 +30,7 @@
 parser.add_argument('--inflate_to_sphere_implicit', dest='inflate_to_sphere_implicit', type=str, default='500,500',
                     help='Parameters for inflate_to_sphere_implicit. Larger values are necessary '
                          'for larger brain size.')
-parser.add_argument('--distance-threshold', dest='distance_threshold', default=1.0, type=float,
+parser.add_argument('--distance-threshold', dest='distance_threshold', default=0.6, type=float,
                     help='Maximum distance error to allow without using subsampling')
 parser.add_argument('--target-smoothness', dest='target_smoothness', type=float, default=0.2,
                     help='Target mean smoothness error for how many iterations of adapt_object_mesh to perform.')

extract_cp/extract_surface.py

@@ -18,8 +18,8 @@
 
 _LOG_PREFIX = b'[' + os.path.basename(__file__).encode(encoding='utf-8') + b']'
 
-BAD_SMTHERR = 2.0
-BAD_DISTERR = 2.0
+BAD_SMTHERR = 10.0
+BAD_DISTERR = 0.6
 
 
 def extract_surface(mask: Path, surface: Path, params: Parameters):

setup.py

@@ -2,7 +2,7 @@
 
 setup(
     name='extract_cp',
-    version='2.1.0',
+    version='2.1.1',
     description='Fetal brain MRI CP surface extraction using CIVET marching-cubes',
     author='Jennings Zhang',
     author_email='Jennings.Zhang@childrens.harvard.edu',