TEEM(1)

💖 TEEM(1) — the pull library, but make it a group chat 💖

okay so first things first: this is section 1 of the User Commands manual, the page is called TEEM, and today's main character is teem-puller. strap in bestie, there's like 60 flags. 🎀

✨ NAME ✨

/usr/bin/teem-puller — command-line interface to the "pull" library. that's it. that's the whole vibe. 💅

🦋 SYNOPSIS 🦋

here's the shape of the thing, fr fr:

teem-puller [@file ...] [-int <int>] [-enr <spec>] \fR

[-ens <spec>] [-enw <spec>] [-efs <bool>] [-nave <bool>] [-cbst <bool>] \ [-noadd] [-usa <bool>] [-pcet <bool>] [-nobin] [-lti <bool>] \ [-por <bool>] [-npcwza <bool>] [-ubfgl <bool>] [-ratb <bool>] \ [-svec <vec>] [-gssr <rad>] [-v <verbosity>] -vol <vol0 vol1 ...> \ -info <info0 info1 ...> [-k00 <kern00>] [-k11 <kern11>] [-k22 <kern22>] \ [-sscp <path>] [-kssb <kernel>] [-kssr <kernel>] [-nss <# scl smpls>] \ [-np <# points>] [-halton] [-ppv <# pnts/vox>] [-ppvzr <z range>] \ [-jit <jitter>] [-pi <npos>] [-step <step>] [-csm <step>] [-snap <# iters>] [-maxi <# iters>] [-stim <# iters>] [-maxci <# iters>] \ [-irad <scale>] [-srad <scale>] [-bws <bin width>] [-alpha <alpha>] \ [-beta <beta>] [-gamma <gamma>] [-theta <theta>] [-wall <k>] [-eip <k>] \ [-ess <scl>] [-oss <scl>] [-edmin <frac>] [-edpcmin <frac>] \ [-fnnm <frac>] [-pcp <period>] [-iad <# iters>] [-icb <# iters>] \ [-ac3c <ac3c>] [-sit <sit>] [-rng <seed>] [-pbm <mod>] [-eiphl <hl>] \ [-nt <# threads>] [-nprob <prob>] [-pprob <prob>] [-addlog <fname>] \ [-o <nout>] [-eob <base>]

@file ... = response file(s) containing command-line arguments

(and yes, that stray \fR up there is literally in the original — a roff escape that escaped. no notes. 🫶)

🌸 DESCRIPTION 🌸

/usr/bin/teem-puller is the command-line interface to the "pull" library, bestie. that's the whole job description and honestly? slay. 🔥

but listen — if you publish research using this tool or the "pull" library, you gotta cite this paper. it's giving academic main character energy, so give credit where credit is due:

Gordon L. Kindlmann, Ra{'u}l San Jos{'e} Est{'e}par, Stephen M. Smith, Carl-Fredrik Westin. Sampling and Visualizing Creases with Scale-Space Particles. IEEE Trans. on Visualization and Computer Graphics, 15(6):1415-1424 (2009).

🧚 the flags, one by one (yes, all of them) 🧚

okay bestie, this is the long part. every single option, its argument, and its default. no skips, no shortcuts, we're eating the whole plate 🍓

• -int <int> — inter-particle energy type (interaction type); default: "justr"
• -enr <spec> — inter-particle energy, radial component (energy specification); default: "cotan"
• -ens <spec> — inter-particle energy, scale component (energy specification); default: "zero"
• -enw <spec> — windowing to create locality with additive scale-space interaction ("-int add") (energy specification); default: "butter:16,0.8"
• -efs <bool> — whether or not strength contributes to particle-image energy (bool); default: "false"
• -nave <bool> — whether or not to nix points at edge of volume, where gage had to invent values for kernel support (bool); default: "false"
• -cbst <bool> — during initialization, try constraint satisfaction before testing seedThresh (bool); default: "false"
• -noadd — turn off adding during population control
• -usa <bool> — allow volumes to have different shapes (false is safe as different volume sizes are often accidental) (bool); default: "false"
• -pcet <bool> — use neighbor-counting "enough" heuristic to bail out of pop cntl (bool); default: "true"
• -nobin — turn off spatial binning (which prevents multi-threading from being useful), for debugging or speed-up measurement
• -lti <bool> — impose liveThresh on initialization (bool); default: "true"
• -por <bool> — permute points during rebinning (bool); default: "true"
• -npcwza <bool> — no pop cntl with zero alpha (bool); default: "false"
• -ubfgl <bool> — use beta for gamma learning (bool); default: "false"
• -ratb <bool> — be choosy when adding points to bins to avoid overlap (bool); default: "true"
• -svec <vec> — if non-zero (length), vector to use for displaying scale in 3-space (3 doubles); default: "0 0 0"
• -gssr <rad> — if non-zero (length), scaling of scale to cylindrical tensors (double); default: "0.0"
• -v <verbosity> — verbosity level (int); default: "1"
• -vol <vol0 vol1 ...> — input volumes, in format <filename>:<kind>:<volname> (1 or more meetPullVols)
• -info <info0 info1 ...> — info definitions, in format <info>[-c]:<volname>:<item>[:<zero>:<scale>] (1 or more meetPullInfos)
• -k00 <kern00> — kernel for gageKernel00 (kernel specification); default: "cubic:1,0"
• -k11 <kern11> — kernel for gageKernel11 (kernel specification); default: "cubicd:1,0"
• -k22 <kern22> — kernel for gageKernel22 (kernel specification); default: "cubicdd:1,0"
• -sscp <path> — path (without trailing /) for where to read/write pre-blurred volumes for scale-space (string); default: "./"
• -kssb <kernel> — blurring kernel, to sample scale space (kernel specification); default: "ds:1,5"
• -kssr <kernel> — kernel for reconstructing from scale space samples (kernel specification); default: "hermite"
• -nss <# scl smpls> — if using "-ppv", number of samples along scale axis for each spatial position (unsigned int); default: "1"
• -np <# points> — number of points to start in system (unsigned int); default: "1000"
• -halton — use Halton sequence initialization instead of uniform random
• -ppv <# pnts/vox> — number of points per voxel to start in simulation (need to have a seed thresh vol, overrides "-np") (unsigned int); default: "0"
• -ppvzr <z range> — range of Z slices (1st num < 2nd num) to do ppv in, or, "1 0" for whole volume (2 unsigned ints); default: "1 0"
• -jit <jitter> — amount of jittering to do with ppv (double); default: "0"
• -pi <npos> — 4-by-N array of positions to start at (overrides "-np") (nrrd); default: ""
• -step <step> — initial step size for gradient descent (double); default: "1"
• -csm <step> — convergence criterion for constraint satisfaction (double); default: "0.0001"
• -snap <# iters> — if non-zero, # iters between saved snapshots (unsigned int); default: "0"
• -maxi <# iters> — if non-zero, max # iterations to run whole system (unsigned int); default: "0"
• -stim <# iters> — if non-zero, max # iterations to allow a particle to be stuck before nixing (unsigned int); default: "5"
• -maxci <# iters> — if non-zero, max # iterations for contraint enforcement (unsigned int); default: "15"
• -irad <scale> — particle radius in spatial domain (double); default: "1"
• -srad <scale> — particle radius in scale domain (double); default: "1"
• -bws <bin width> — spatial bin width as multiple of spatial radius (double); default: "1.001"
• -alpha <alpha> — blend between particle-image (alpha=0) and inter-particle (alpha=1) energies (double); default: "0.5"
• -beta <beta> — when using Phi2 energy, blend between pure space repulsion (beta=0) and scale attraction (beta=1) (double); default: "1.0"
• -gamma <gamma> — scaling factor on energy from strength (double); default: "1.0"
• -theta <theta> — slope of increasing livethresh wrt scale (double); default: "0.0"
• -wall <k> — spring constant on walls (double); default: "0.0"
• -eip <k> — amount by which its okay for per-particle energy to increase during gradient descent process (double); default: "0.0"
• -ess <scl> — when energy goes up instead of down, scale step size by this (double); default: "0.5"
• -oss <scl> — opportunistic scaling (hopefully up, >1) of step size on every iteration (double); default: "1.0"
• -edmin <frac> — convergence threshold: stop when fractional improvement (decrease) in energy dips below this (double); default: "0.0001"
• -edpcmin <frac> — population control is triggered when energy improvement goes below this threshold (double); default: "0.01"
• -fnnm <frac> — don't nix if this fraction (or more) of neighbors have been nixed (double); default: "0.25"
• -pcp <period> — # iters to wait between attempts at population control (unsigned int); default: "20"
• -iad <# iters> — # iters to run descent on tentative new points during PC (unsigned int); default: "10"
• -icb <# iters> — periodicity of calling rendering callback (unsigned int); default: "1"
• -ac3c <ac3c> — allow codimensions 3 constraints (bool); default: "false"
• -sit <sit> — scale is tau (bool); default: "false"
• -rng <seed> — base seed value for RNGs (unsigned int); default: "42"
• -pbm <mod> — progress bin mod (unsigned int); default: "50"
• -eiphl <hl> — half-life of energyIncreasePermute ("-eip") (unsigned int); default: "0"
• -nt <# threads> — number of threads hoover should use (int); default: "1"
• -nprob <prob> — do full neighbor discovery with this probability (double); default: "1.0"
• -pprob <prob> — probe local image values with this probability (double); default: "1.0"
• -addlog <fname> — name of file in which to log all particle additions (string); default: ""
• -o <nout> — output volume (string); default: "-"
• -eob <base> — save extra info (besides position), and use this string as the base of the filenames. Not using this means the extra info is not saved. (string); default: ""

heads up bestie: that -eob one is a little all-or-nothing — if you don't pass it, the extra info just doesn't get saved. no take-backs. 😭

👑 SEE ALSO 👑

the full documentation for Teem lives as a Texinfo manual, and if the info program and the Teem programs are properly installed at your site, this:

info Teem

should hand you the complete manual. go get it, queen. 💜

and that's the whole page, bestie — teem version 1.11.0, from April 2012, section 1 of the manual, signed sealed and slayed. mwah. 💅✨