Programs · FSL

betsurf

Original
FSL 6.0.7.23
Command line
larmorx fsl betsurf
Python
lx.fsl.betsurf
Ports
  • replica larmorx-nc FSL Licence: non-commercial use only validated
  • clean room larmorx Apache-2.0 experimental
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

text
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):

text
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
text
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 times

Python

python
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",
) -> BetsurfResult

Where 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 N
n_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-room
implementation="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|reproduce
upstream_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.

python
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_mask
bash
larmorx 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 T1w

Ports

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-nc holds it, under FSL’s licence, and larmorx runs it as a separate program, larmorx-nc fsl bet|bet2|betsurf, when larmorx-nc is 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 of larmorx, 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: