PULLER(1)

💅 PULLER(1) — User Commands ✨

okay bestie, sit DOWN, because this is puller(1), the command-line interface to the “pull” library, and she is a lot in the best way. this is the manual page for the pull library's front door, and yes there are like seventy flags, and yes we're going to go through every single one of them, because that's what we do here. 🫶

---

🌸 NAME 🌸

puller — command-line interface to the “pull” library

---

✨ SYNOPSIS ✨

no cap, here's the whole invocation, every bracket exactly where it lives:

puller [@file ...]  [-int <int>] [-enr <spec>] [-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>]

heads up, the required ones are -vol and -info (no brackets on those, they're mandatory, main character energy only) and literally everything else is optional. also peep that the scale-samples flag shows up as -nss in the synopsis and -nssr in the options list below — that's genuinely how the page reads, so keep both spellings in your head 💀

---

🎀 OPTIONS 🎀

• @file ... — response file(s) containing command-line arguments
• -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 population control (bool); default: “false”
• -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 population control 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) — required, bestie, no skimping
• -info <info0 info1 ...> — info definitions, in format <info>[-c]:<volname>:<item>[:<zero>:<scale>] (1 or more meetPullInfos) — also required, slay
• -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”
• -nssr <# 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 <# p[nts/vox> — number of points per voxel to start in simulation (need to have a seed threshold volume, overrides “-np”) (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 with respect to scale (double); default: “0.0”
• -wall <k> — spring constant on walls (double); default: “0.0”
• -eip <k> — amount by which it’s 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> — filename for saving computed positions (string); default: “-”
• -eob <base> — save extra info (besides position), and use this string as the base of the filenames. Not using this eans the extra info is not saved. (string); default: “”

---

👑 NOTES 👑

if you publish research using this tool or the “pull” library, you GOTTA cite the paper, it's the rules, it's giving academic integrity:

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).

---

🦋 SEE ALSO 🦋

gprobe(1), ilk(1), mrender(1), miter(1), nrrdSanity(1), overrgb(1), tend(1), unu(1), vprobe(1)

---

and that's the whole page, bestie 💖 this was PULLER(1) from the User Commands section, dated April 2021, and you ATE. now go render some creases. periodt. 💅✨🎀