EDIT(nged)

✨ NAME ✨

edit — edit objects in the database by translating, rotating, scaling, and other operations. (this is EDIT(nged), straight out of the BRL-CAD User Commands lineup — hiii bestie 💖)

🎀 SYNOPSIS 🎀

edit [options] [geometry_specifier] subcommand [subcommand_args]

🦋 DESCRIPTION 🦋

okay so edit transforms one or more objects in a BRL-CAD database. it's got a whole composable set of subcommands (translate, rotate, scale, and friends) plus a flexible geometry specifier syntax that can name objects by bare name, slash-separated path, URI, or via the active selection state. it's giving swiss army knife, fr fr 💅

every geometry-altering subcommand follows the exact same lifecycle, no cap:

1. identify the object(s) to edit via a geometry specifier or the active selection.
2. load the object into a temporary edit buffer (or create a fresh buffer entry if none exists).
3. apply the requested transformation.
4. commit the result to the database — unless -i is given, which leaves the buffer entry pending for further operations.

and the checkpoint, revert, reset, and mat subcommands are the ones doing lifecycle management for that temporary buffer. they're the backstage crew, lowkey iconic 🫶

---

🌈 GEOMETRY SPECIFIERS 🌈

a geometry specifier tells edit which object to act on. here are the supported forms, bestie:

• bare name — a top-level object name (e.g. sph.s, assembly).
• slash-separated path — a hierarchical path whose rightmost component is the object to edit and the preceding components supply the transformation matrix context (e.g. assembly/subpart/sph.s).
• URI with fragment — a name followed by # and a feature key (e.g. sph.s#vertex0) when DbiState is available.
• URI with query — a name followed by ? and a query string (e.g. sph.s?face=top) when DbiState is available.
• . (batch marker) — each object in the target list is used as its own reference point. useful for batch operations where each object moves independently.
• selection fallback — if no geometry specifier is given on the command line, the current default selection state (if any) is used automatically. it just knows. main character energy 🌟

💜 OPTIONS 💜

• -h, --help — print help. the classic cry for guidance.
• -v, --verbose — increase verbosity. more words, more yap, more info.
• -S, --selection — ignore any explicit command-line geometry specifier and operate on the active selection state instead.
• -f, --force — force: apply the operation, write the result to the database, and clear any pending conflict state. no thoughts, just send it 🔥
• -F, --abandon — abandon the intermediate buffer state and revert to the on-disk geometry. equivalent to revert followed by discarding the buffer entry. it's giving "we don't know her" 💀
• -i, --intermediate — intermediate mode: apply the transformation to the temporary buffer only; do not write to the database. use checkpoint / revert / reset to manage the buffer lifecycle.
• Conflict arbiter — when an explicit geometry specifier is given and the same object also appears in the active selection, edit reports a conflict and requires one of the four arbiter flags (-S, -f, -F, or -i) to resolve it. this prevents accidental divergence between a command-line edit and an interactive selection. it's a vibe check, basically ✋
• --list-all-prim-ops — print a human-readable list of available descriptor-defined edit operations for all primitive types.
• --list-all-prim-ops=json — print the same information as a JSON array. same tea, machine-readable mug ☕

---

🧚 PRIMITIVE OPERATION LISTING 🧚

edit supports both human-readable and JSON forms for descriptor-driven primitive operation discovery. two flavors, both slay.

top-level listing (all primitive types)

edit --list-all-prim-ops
edit --list-all-prim-ops=json

per-primitive listing by type name

edit tor
edit tor --list-ops
edit tor --list-ops=json

per-primitive listing by object name

edit tor.s -h

the general pattern is:

• human-readable: edit <primitive_type> --list-ops
• JSON: edit <primitive_type> --list-ops=json

---

👑 SUBCOMMANDS 👑

translate (alias: tra)

edit [options] geometry translate [-a|-r] [-x|-y|-z] [-k FROM] TO
edit [options] geometry tra X Y Z

translates the object's position. see edit translate(nged) for the complete option reference and examples. moving day, but make it geometry 🚚

• -a — interpret TO as an absolute position in model space.
• -r — interpret TO as a relative delta from the current keypoint (default).
• -x, -y, -z — restrict the translation to the specified axis only.
• -k FROM — set the reference keypoint. FROM may be an object name or a position x y z.

Example 1. Quick examples

mged> edit sph.s translate -a 15 0 0
mged> edit sph.s translate -r 5 0 0
mged> edit sph.s translate -k sph.s -a other.s
mged> edit sph.s tra 5 0 0

rotate (alias: rot)

edit [options] geometry rotate [X_DEG [Y_DEG [Z_DEG]]]
edit [options] geometry rotate [-x|-y|-z] DEGREES
edit [options] geometry rotate [-R] [-k AXIS_FROM] [-a|-r AXIS_TO]
    [-c CENTER] [-O ANGLE_ORIGIN] [-d DEGREES]

rotates the object using Euler angles or an explicit axis of rotation. see edit rotate(nged) for the complete option reference, conceptual model, and examples. spin spin spin 🌀

• -R — interpret angle values as radians.
• -x, -y, -z — restrict the rotation to the specified axis (Euler mode).
• -k AXIS_FROM, -a/-r AXIS_TO — supply an explicit axis of rotation (axis mode).
• -c CENTER — set the pivot center (defaults to bounding-box center).
• -O ANGLE_ORIGIN, -d DEGREES — set the angle origin and explicit rotation angle.

Example 2. Quick examples

mged> edit ell.s rotate 0 0 90
mged> edit ell.s rotate -z 90
mged> edit cube rotate -k sphere1 -a sphere2 -d 90

scale (alias: sca)

edit [options] geometry scale FACTOR
edit [options] geometry scale X_FACTOR Y_FACTOR Z_FACTOR
edit [options] geometry scale [-k FROM] [-a|-r TO] [-c CENTER]

scales the object by a uniform or per-axis factor. see edit scale(nged) for the complete option reference, the SCALE reference-frame model, and examples. big mood, literally 📏

• -k FROM — reference "from" position. defaults to the object keypoint.
• -a TO, -r TO — "to" position (absolute or relative). together with -k, defines the reference scale vector.
• -c CENTER — center of the scaling operation.

Example 3. Quick examples

mged> edit sph.s scale 2
mged> edit sph.s scale 2 2 2
mged> edit sph.s scale -k 0 0 0 -a 2 2 2

checkpoint

edit [options] geometry checkpoint

loads the named geometry into the temporary edit buffer (creating a new buffer entry if one does not already exist) without applying any transformation. a subsequent -i operation will then modify only the buffer without touching the database, and a revert can undo those changes. it's a save point, bestie 🎀

revert

edit [options] geometry revert

reverts the in-buffer state of the named geometry to its most recent checkpoint state and writes that state back to the database. returns an error if no buffer entry exists for the object. ctrl+z but make it official ↩️

reset

edit [options] geometry reset

discards the temporary buffer entry for the named geometry without writing anything to the database. equivalent to abandoning an in-progress edit. we simply do not perceive it 🙈

mat

edit [options] geometry mat M00 M01 ... M33

applies an arbitrary 4×4 matrix (16 row-major values) to the geometry. the matrix is passed directly to the underlying librt edit layer. raw math delivered straight to the source 🔢

Example 4. Example: Apply a 90° Z-rotation matrix to ell.s

mged> edit ell.s mat 0 -1 0 0  1 0 0 0  0 0 1 0  0 0 0 1

perturb

edit [options] geometry perturb FACTOR

applies a random perturbation of magnitude FACTOR to the geometry. useful for sensitivity studies and mesh stress-testing. the perturbation is applied once per invocation; the random seed is derived from the session state. chaos, but make it scientific 🌪️

requires that the underlying primitive type support ft_perturb.

---

⭐ EXAMPLES ⭐

these illustrate the most common edit workflows. see edit translate(nged), edit rotate(nged), and edit scale(nged) for comprehensive examples of each subcommand.

Example 5. Translate a sphere to an absolute position

mged> edit sph.s translate -a 15 0 0

Example 6. Rotate a cube 45° around the Z-axis

mged> edit cube rotate -z 45

Example 7. Double the size of a sphere

mged> edit sph.s scale 2

Example 8. Intermediate edit workflow: checkpoint, modify, revert if needed

create a checkpoint (snapshot to revert to):

mged> edit tor.s checkpoint

apply a tentative translation (stays in buffer):

mged> edit -i tor.s translate -r 5 0 0

if satisfied, write to disk:

mged> edit tor.s translate -r 0 0 0

if not satisfied, roll back to the checkpoint:

mged> edit tor.s revert

Example 9. Edit based on the active selection

with objects already selected in the viewer:

mged> edit translate -a 10 0 0

force the command-line specifier to override the selection:

mged> edit -f sph.s translate -a 10 0 0

---

💫 SEE ALSO 💫

edit translate(nged), edit rotate(nged), edit scale(nged), translate(nged), rotate(nged), scale(nged), protate(nged), pscale(nged), ptranslate(nged), edarb(nged) — go read the whole friend group 🫶

🌸 AUTHOR 🌸

BRL-CAD Team

🐛 BUG REPORTS 🐛

reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org. tell them everything, they want the tea ☕

---

✨ that's the whole page!! brought to you by BRL-CAD, filing under EDIT(nged), and dated the way the original footer says — go off, you understood the assignment 💅💖