Programs · FSL
bet2
bet2 is FSL’s brain extraction itself, which the bet script runs.
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl bet2- Python
lx.fsl.bet- 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
It deforms a tessellated sphere onto the brain’s surface in a head image and writes the brain and, on request, its mask, its outline, an approximate skull and the surface as a mesh.
Command line
larmorx fsl bet2 <input_fileroot> <output_fileroot> [options]Everything after larmorx fsl bet2 is the original’s command line: the arguments of FSL 6.0.7.23’s bet2, 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 bet2 ...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.
bet2's usage text, as the clean room prints it
Part of FSL (ID: 2412.6-dirty)
BET (Brain Extraction Tool) v2.1 - FMRIB Analysis Group, Oxford
Usage:
bet2 <input_fileroot> <output_fileroot> [options]
Optional arguments (You may optionally specify one or more of):
-o,--outline generate brain surface outline overlaid onto original image
-m,--mask generate binary brain mask
-s,--skull generate approximate skull image
-n,--nooutput don't generate segmented brain image output
-f <f> fractional intensity threshold (0->1); default=0.5; smaller values give larger brain outline estimates
-g <g> vertical gradient in fractional intensity threshold (-1->1); default=0; positive values give larger brain outline at bottom, smaller at top
-r,--radius <r> head radius (mm not voxels); initial surface sphere is set to half of this
-w,--smooth <r> smoothness factor; default=1; values smaller than 1 produce more detailed brain surface, values larger than one produce smoother, less detailed surface
-c <x y z> centre-of-gravity (voxels not mm) of initial mesh surface.
-t,--threshold -apply thresholding to segmented brain image and mask
--ct -treat input as CT image (default is MRI)
--binaryMask <image> Generate mesh from existing mask
-e,--mesh generates brain surface as mesh in vtk format
-v,--verbose switch on diagnostic messages
-h,--help displays this help, then exitsPython
lx.fsl.bet(
image: Any,
*,
frac: float = 0.5,
gradient: float = 0.0,
radius: float | None = None,
centre: Sequence[float] | None = None,
smoothness: float = 1.0,
threshold: bool = False,
head_ct: bool = False,
variation: Variation | None = None,
t2: Any = None,
brain: bool = True,
mask: bool = False,
outline: bool = False,
skull: bool = False,
mesh: bool = False,
tanh: Tanh = "glibc",
fsl_data: str | os.PathLike[str] | None = None,
n_threads: int = 1,
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
) -> BetResultWhere Variation is one of "robust", "small_fov", "fmri", "eyes", "bias", "surfaces", "surfaces_t2"; Tanh is one of "glibc", "correctly-rounded"; ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".
The brain, as FSL’s bet2 (or, with variation, the bet script) extracts it.
lx.fsl.bet without variation runs bet2 (the function’s description: bet).
Its result, BetResult, holds what bet computed (None for what was not asked for).
| Field | Type | What it holds |
|---|---|---|
brain |
Image | None |
The input with every voxel outside the brain 0 (float32; 4D with "fmri"). |
mask |
Image | None |
The brain mask (int16, 1 inside). |
outline |
Image | None |
The surface drawn on the input at its maximum (float32; -o). |
skull |
Image | None |
An approximate skull (int16; -s). |
mesh |
Surface | None |
The brain’s surface (-e): its vertices (n, 3) in FSL’s millimetre coordinates and its triangles (m, 3). |
surfaces |
BetsurfResult | None |
The inner skull, outer skull and scalp surfaces, their masks, the skull’s mask and the surfaces’ outlines ("surfaces" and "surfaces_t2": betsurf -o -m -s). |
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 bet2 accepts (crates/larmorx-fsl/src/cli/bet2.rs) and the arguments of lx.fsl.bet (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 |
|---|---|---|---|
<input> <output> |
image; the result |
outputs <output>, _mask, _overlay, _skull, _mesh.vtk |
|
-f <f> |
frac |
0.5 |
0 to 1; smaller gives a larger brainFSL: “fractional intensity threshold (0->1); default=0.5; smaller values give larger brain outline estimates” |
-g <g> |
gradient |
0.0 |
-1 to 1; positive gives a larger brain at the bottomFSL: “vertical gradient in fractional intensity threshold (-1->1); default=0; positive values give larger brain outline at bottom, smaller at top” |
-r <r>, --radius |
radius |
None |
mm; the initial sphere is half of itFSL: “head radius (mm not voxels); initial surface sphere is set to half of this” |
-c <x y z> |
centre |
None |
voxels of the file as stored; 0 0 0 is “not given” (the centre of gravity), as in FSLFSL: “centre-of-gravity (voxels not mm) of initial mesh surface.” |
-w <r>, --smooth |
smoothness |
1.0 |
bet2 only (bet does not pass it)FSL: “smoothness factor; default=1; values smaller than 1 produce more detailed brain surface, values larger than one produce smoother, less detailed surface” |
-t, --threshold |
threshold=True |
False |
also thresholds the brain and maskFSL: “apply thresholding to segmented brain image and mask” |
--ct |
head_ct=True |
False |
bet2 only: the input in Hounsfield unitsFSL: “treat input as CT image (default is MRI)” |
-m, --mask |
mask=True |
False |
FSL: “generate binary brain mask” |
-o, --outline |
outline=True |
False |
FSL: “generate brain surface outline overlaid onto original image” |
-s, --skull |
skull=True |
False |
FSL: “generate approximate skull image” |
-n, --nooutput |
brain=False |
True |
FSL: “don’t generate segmented brain image output” |
-e, --mesh |
mesh=True |
False |
VTK; also switches the self-intersection test to the exact oneFSL: “generates brain surface as mesh in vtk format” |
-v, --verbose |
(command line only) | FSL: “switch on diagnostic messages” | |
--binaryMask <image> |
(command line only) | FSL: “Generate mesh from existing mask” | |
-h, --help |
(command line only) | FSL: “displays this help, then exits” | |
--parameter_d1=, --parameter_d2= |
(command line only) | hidden search depths (7 and 3) | |
--tanh=correctly-rounded (LARMORX’s own option; also --tanh correctly-rounded, and passed on by bet) |
tanh="correctly-rounded" |
"glibc" |
computes the surface’s smoothness weight with the correctly rounded tanh (CORE-MATH’s, larmorx_core::math::tanh) instead of glibc 2.35’s, which FSL calls and which is the default (glibc; decision GLIBC-06). No notice: it is asked for. Where a surface self-intersects and is found again, the last bit can change the result (4 of the 13 real images of the clean room’s standard comparison: its findings). Clean room only: implementation="replica" refuses it, and "auto" runs the clean room |
FSLOUTPUTTYPE |
(always NIfTI-1 in Python) | on the command line read from the environment, as FSL does (unset: NIFTI_GZ, FSL-11) |
|
(bet's variations) |
variation, t2, fsl_data |
variation=None, t2=None, fsl_data=None |
bet only (its options) |
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 bet2 ...) and are arguments of lx.fsl.bet. Each one given wins over its environment variable, which keeps working.
| Command line, then Python | What it does |
|---|---|
--n-threads Nn_threads=1 |
Threads (0 = all); the result does not depend on it. 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" |
"auto" (default): the replica in larmorx-nc when it is installed, else the clean room (always the clean room with tanh="correctly-rounded"); "replica": the replica (ReplicaNotFoundError without it); "clean-room": the clean room (FSL’s behaviour within the thresholds of its validation record, docs/validation/fsl-bet.md). The variable LARMORX_IMPLEMENTATION in 0.1.0rc1. |
--upstream-defects fix|reproduceupstream_defects="fix" |
"fix" (default) or "reproduce" (FSL’s output); an UpstreamDefectWarning names each defect that changed the result. 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). The command lines run as python -m larmorx.
import larmorx as lx
b = lx.fsl.bet("T1w.nii.gz", mesh=True)
b.brain, b.meshlarmorx fsl bet2 T1w.nii.gz T1w_brain -ePorts
bet2 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 record holds the same programs. Of its 380 brains,
masks and outlines (betsurf’s counted apart), 378 are FSL’s bit for bit; the two others are
bet -B’s. 11 of 11 meshes have FSL’s vertices to the file’s 6 decimals.
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 bet2’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 bet2 shares with the page’s other programs: