Programs · FSL
betsurf
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl betsurf- Python
lx.fsl.betsurf- Ports
- replica
larmorx-ncFSL Licence: non-commercial use only validated - clean room
larmorxApache-2.0 experimental
- replica
- Evidence
- every comparison with FSL
- Source
- made from docs/api/fsl-bet.md and the code
What it does
betsurf finds the inner skull, the outer skull and the scalp of a head, from bet2’s brain
surface (-e), the T1 image (and a T2) and the T1’s registration to MNI152.
Command line
larmorx fsl betsurf [options] <t1> <t2> <bet_mesh.vtk> <t1_to_standard.mat> <output>
larmorx fsl betsurf --t1only [options] <t1> <bet_mesh.vtk> <t1_to_standard.mat> <output>Everything after larmorx fsl betsurf is the original’s command line: the arguments of FSL 6.0.7.23’s betsurf, as FSL takes them. LARMORX’s own options stand between larmorx and the family fsl, so they never meet the original’s (below):
larmorx
[--n-threads N]
[--implementation auto|replica|clean-room]
[--upstream-defects fix|reproduce]
fsl betsurf ...From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.
betsurf's usage text, as the clean room prints it
Part of FSL (ID: 2412.6-dirty)
BETSURF (BET Surface Finder) v2.1 - FMRIB Analysis Group, Oxford
Usage:
betsurf [options] <t1> <t2> <bet_mesh.vtk> <t1_to_standard.mat> <output>
betsurf --t1only [options] <t1> <bet_mesh.vtk> <t1_to_standard.mat> <output>
Optional arguments (You may optionally specify one or more of):
-h,--help displays this help, then exits
-v,--verbose switch on diagnostic messages
-1,--t1only extraction with t1 only
-o,--outline generates all surface outlines
-m,--mask generates binary masks from the meshes
-s,--skullmask generates skull binary mask
-p,--increased_precision <int> retessellates the meshes the indicated number of timesPython
lx.fsl.betsurf(
t1: Any,
brain_surface: Surface | str | os.PathLike[str],
t1_to_standard: Any,
*,
t2: Any = None,
masks: bool = True,
skull_mask: bool = False,
outlines: bool = False,
precision: int = 0,
n_threads: int = 1,
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
) -> BetsurfResultWhere ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".
The inner skull, outer skull and scalp surfaces, as FSL’s betsurf finds them.
brain_surface is bet(..., mesh=True).mesh or a VTK file; t1_to_standard is FLIRT’s 4 x 4
matrix to MNI152 (a path or an array; it only decides which profiles cross the eyes). Without t2
the surfaces come from the T1 alone (--t1only). precision is -p. lx.fsl.read_vtk(path)
reads a VTK mesh as FSL writes it.
Its result, BetsurfResult, holds what betsurf computed.
| Field | Type | What it holds |
|---|---|---|
inskull |
Surface |
The inner skull, outer skull and scalp surfaces. |
outskull |
Surface |
The inner skull, outer skull and scalp surfaces. |
outskin |
Surface |
The inner skull, outer skull and scalp surfaces. |
inskull_mask |
Image | None |
Their masks on the T1’s grid (int16, 1 inside), with masks=True (-m). |
outskull_mask |
Image | None |
Their masks on the T1’s grid (int16, 1 inside), with masks=True (-m). |
outskin_mask |
Image | None |
Their masks on the T1’s grid (int16, 1 inside), with masks=True (-m). |
skull_mask |
Image | None |
The skull between the two skull surfaces, on the T1’s grid (int16), with skull_mask=True (-s). |
inskull_outline |
Image | None |
The surfaces drawn as 1 on the T1’s grid (int16), with outlines=True (-o). |
outskull_outline |
Image | None |
The surfaces drawn as 1 on the T1’s grid (int16), with outlines=True (-o). |
outskin_outline |
Image | None |
The surfaces drawn as 1 on the T1’s grid (int16), with outlines=True (-o). |
Options
Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options betsurf accepts (crates/larmorx-fsl/src/cli/betsurf.rs) and the arguments of lx.fsl.betsurf (python/larmorx/fsl/bet.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.
| FSL option | Python | Default | Notes |
|---|---|---|---|
<t1> [<t2>] <bet_mesh.vtk> <t1_to_standard.mat> <output> |
t1, t2, brain_surface, t1_to_standard; the result |
t2=None |
outputs <output>_inskull_mesh.vtk, _outskull_mesh.vtk, _outskin_mesh.vtk (always), their images |
-1, --t1only |
t2=None |
None |
the surfaces from the T1 aloneFSL: “extraction with t1 only” |
-m, --mask |
masks=True (default) |
True |
<output>_inskull_mask, _outskull_mask, _outskin_maskFSL: “generates binary masks from the meshes” |
-s, --skullmask |
skull_mask=True |
False |
<output>_skull_mask (the masks are made without -m too)FSL: “generates skull binary mask” |
-o, --outline |
outlines=True |
False |
<output>_inskull_mesh, _outskull_mesh, _outskin_mesh images: each surface drawn as 1FSL: “generates all surface outlines” |
-p <int>, --increased_precision=<int> |
precision |
0 |
each surface retessellated that many times, 100 more steps each (the meshes written are the retessellated ones); FSL’s int: strtol of base 0 (0x10 reads, 08 does not); larmorx refuses more than 10 (the meshes would not fit any memory)FSL: “retessellates the meshes the indicated number of times” |
-v, --verbose |
(command line only) | extracting profiles, the profiles cast and the percentage set aside (the dropped ones and those of which only the scalp counts), then each phaseFSL: “switch on diagnostic messages” |
|
-h, --help |
(command line only) | the usage, exit 0FSL: “displays this help, then exits” | |
the mesh name manual_input |
(command line only) | the name read from standard input (larmorx refuses at its end, where FSL waits forever); the name c cancels (an empty mesh: refused, FSL-52) |
|
FSLOUTPUTTYPE |
(always NIfTI-1 in Python) | read when the first image is written, as FSL does (unset: NIFTI_GZ, FSL-11) |
LARMORX’s own options
From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.
They stand between larmorx and fsl on the command line (larmorx --n-threads 4 fsl betsurf ...) and are arguments of lx.fsl.betsurf. Each one given wins over its environment variable, which keeps working.
| Command line, then Python | What it does |
|---|---|
--n-threads Nn_threads=1 |
As for bet (the clean room’s record: docs/validation/fsl-bet.md). Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1. |
--implementation auto|replica|clean-roomimplementation="auto" |
As for bet (the clean room’s record: docs/validation/fsl-bet.md). The variable LARMORX_IMPLEMENTATION in 0.1.0rc1. |
--upstream-defects fix|reproduceupstream_defects="fix" |
As for bet (the clean room’s record: docs/validation/fsl-bet.md). The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1. |
Examples
The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: T1w.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), T1w_to_MNI152.mat (the identity as a 4 × 4 text matrix). The command lines run as python -m larmorx.
import larmorx as lx
# The skull and scalp: bet2's mesh, then betsurf with the T1's registration to MNI152
b = lx.fsl.bet("T1w.nii.gz", mesh=True)
s = lx.fsl.betsurf("T1w.nii.gz", b.mesh, "T1w_to_MNI152.mat", skull_mask=True)
s.inskull_mask, s.outskull_mask, s.outskin_mask, s.skull_masklarmorx fsl bet2 T1w.nii.gz T1w_brain -e
larmorx fsl betsurf --t1only -o -m -s T1w.nii.gz T1w_brain_mesh.vtk T1w_to_MNI152.mat T1wPorts
betsurf has two ports: a replica and a clean room.
| Port | Package | Licence | Status | Records |
|---|---|---|---|---|
| replica | larmorx-nc |
FSL Licence: non-commercial use only | validated | fsl-bet-replica, fsl-bet-replica-full |
| clean room | larmorx |
Apache-2.0 | experimental | fsl-bet |
The replica gives FSL 6.0.7.23’s exit status, messages and files byte for byte in 201 of the 263
cases of its record, which holds bet, bet2, betsurf, standard_space_roi and fslroi; 47
more are rejected by both. The clean room’s masks and outlines are within its thresholds (a Dice coefficient of at least 0.99, a
boundary distance of at most 1 voxel at the 95th percentile) in 114 of 116, 34 of them bit for bit.
One of the record’s two misses is betsurf’s: the scalp of ds002603 with its T2, whose boundary
distance is 2 voxels at the 95th percentile.
FSL’s licence allows non-commercial use only, so the two ports of bet, bet2 and betsurf, a
replica and a clean room, live in different packages (licensing says what each
package holds):
- The replica is translated from FSL’s source. The package
larmorx-ncholds it, under FSL’s licence, andlarmorxruns it as a separate program,larmorx-nc fsl bet|bet2|betsurf, whenlarmorx-ncis installed (pip install larmorx-nc). - The clean room is written from
specs/bet.md, the BET paper and runs of FSL, without FSL’s source or the replica. It is part oflarmorx, under Apache-2.0 (crates/larmorx-fsl, with its PROVENANCE).
implementation="auto" runs the replica when larmorx-nc is installed, and the clean room
otherwise. "replica" and "clean-room" choose one ("original", 0.1.0rc1’s spelling of
"clean-room", still works). Each image’s implementation names the port that ran. On the
command line, --implementation auto|replica|clean-room before the family chooses alike, from the
next release; in 0.1.0rc1 the variable LARMORX_IMPLEMENTATION chooses (original for the clean
room).
Evidence
How each of betsurf’s ports was measured against FSL, case by case: its evidence.
More in the repository
The API page docs/api/fsl-bet.md holds what betsurf shares with the page’s other programs: