Skip to documentation
BRL-CAD
DocumentationAll documentsEnglish

EDIT(nged)

NAME

edit - Edit objects in the database by translating, rotating, scaling, and other operations.

On this page

SYNOPSIS

edit [options] [geometry_specifier] subcommand [subcommand_args]

DESCRIPTION

The edit command transforms one or more objects in a BRL-CAD database. It supports a composable set of subcommands (translate, rotate, scale, and others) and a flexible geometry specifier syntax that can name objects by bare name, slash-separated path, URI, or via the active selection state.

All geometry-altering subcommands share the same lifecycle:

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

The checkpoint, revert, reset, and mat subcommands provide lifecycle management for the temporary buffer.

GEOMETRY SPECIFIERS

A geometry specifier identifies the object to act on. Supported forms:

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.

OPTIONS

-h, --help

Print help.

-v, --verbose

Increase verbosity.

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

-F, --abandon

Abandon the intermediate buffer state and revert to the on-disk geometry. Equivalent to revert followed by discarding the buffer entry.

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

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

PRIMITIVE OPERATION LISTING

The edit command supports both human-readable and JSON forms for descriptor-driven primitive operation discovery.

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.

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

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

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

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.

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.

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.

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.

Requires that the underlying primitive type support ft_perturb.

EXAMPLES

The following examples 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)

AUTHOR

BRL-CAD Team

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org