## Name

edit translate — Translates the positions of objects, using coordinates, offsets, and objects as reference points.

## Synopsis

`edit translate` [(1) from] (2) to `object`...
(1) [`-n`] `-k` { (4) from_object | (3) from_position }
(2) [`-n`] [ `-a` | `-r` ] { (4) to_object | (3) to_position }
(3) { (5) coords } | { [ `-x` { `x` | (4) x-obj } ] [ `-y` { `y` | (4) y-obj } ] [ `-z` { `z` | (4) z-obj } ] }
(4) [`path/`] `object` [ (5) offset_distance ]
(5) `x` [ `y` [`z`] ]

## DESCRIPTION

Used to move one or more instances of primitive or combination objects. The positions of object's are translated from from to to.

See the edit command's manual for more information.

## EXAMPLES

Example 1. A not particuarlly useful demonstration of the command's capabilities.

`>` `edit translate -k 0 0 0 -a . obj1 obj2 obj3 obj4 obj5`

  Moves every instance of each obj[1-5] in the same direction and by the same distance it is from the origin. The result is a (rather inflexible) "explosion" of the objects from the origin.

Example 2. Move several objects together.

`>` `edit translate -a -z obj1 obj2 obj3 obj4 obj5`

  The from point defaults to the bounding box center of the first target object, which is obj2. Every instance of objects obj2 - obj5 is moved from obj2 to the z-axis of obj1. If the z-coordinate of from was 7, and the z-coordinate of to was 5, then each object would move -2 units in the z-axis.

Example 3. Align several objects to the same point on an axis.

`>` `edit translate -k . -a -z obj1 obj2 obj3 obj4 obj5`

  Sets the elevation of obj[2-5] to the elevation of obj1. Each object uses its own bounding box center as the from point in an operation that moves to the bounding box center of obj1.

Example 4. Move several objects to the same point.

`>` `edit translate -k . -a obj1 obj2 obj3 obj4 obj5`

  Each object uses its own bounding box center as the from point in an operation that moves to the bounding box center of obj1. All objects end up centered on obj2.

Example 5. Explicitly set the z-axis of an obj.

`>` `edit translate -a -z 7.8 obj`

  Moves obj from its bounding box center to 7.8 on the z-axis.

Example 6. Move several objects from their own natural origins to their own bounding box centers.

`>` `edit translate -n -k . -a . obj1 obj2 obj3`

  The objects are moved from their own natural origins to their own bounding box centers.

Example 7. Set the z-axis of the center of one object to the z-axis of the natural origin of another object.

`>` `edit translate -n -a -z obj2/obj3 obj1`

  Moves obj1 up or down from the elevation of its bounding box center to the apparent elevation of the natural origin of the instance of obj3 in obj2.

Example 8. Same result as above, but moving from the natural origin of obj1 rather than its bounding box center.

`>` `edit translate -n -k obj1 -n -a -z obj2/obj3 obj1`
`>` `edit translate -n -k . -n -a -z obj2/obj3 obj1`

Example 9. The use of object paths and individual coordinate specifiers.

`>` `edit translate -a -x 8 -z 42 obj1/obj2/obj3`

  Moves the instance of ob3 in obj2 from the apparent bounding box center of obj3 as offset by obj1/obj2, to x=8, z=42, without moving in the y-axis. Note that this is not the same as -a 8 0 42. Also note that only the matrix of obj2 is modified. No matter the length of the path, only the combination containing the actual object being translated will be modified. If the only component of the path were obj3, then if obj3 were a primitive it would be modified or if obj3 were a combination the matrices of all objects it holds would be modified.

Example 10. Translations using relative positions.

`>` `edit translate -k obj1 -r -z 5 obj2`
`>` `edit translate -a -z obj1 0 0 5 obj2`

  These commands perform the same function. The z-coordinate of the bounding box center of obj2 is moved to the z-coordinate of the bounding box center of obj1 plus 5 units.

Example 11. This example breaks down a particularly complex translation.

`>` `edit translate -k -x c/obj1 1.5 -y c/obj2 0 3 -z c/obj3 0 0 10 -a -x b/c/obj4 2 -y b/c/obj5 0 4 -z b/c/obj6 0 0 20 obj7 obj8`

  Every use of translate involves a from point and a to point. One of the more flexible features of the edit commands is the capability to use an object and an offset to specify each axis of these points individually. The command in this example can be broken down to three simpler commands, in order to ease comprehension:

`>` `edit translate -k -x c/obj1 1.5 -a -x b/c/obj4 2 obj7 obj8`
`>` `edit translate -k -y c/obj2 0 3 -a -y b/c/obj5 0 4 obj7 obj8`
`>` `edit translate -k -z c/obj3 0 0 10 -a -z b/c/obj6 0 0 20 obj7 obj8`

  In the first shortened command, the from point is set to the x-coordinate of the apparent point of the bounding box center of the instance of obj1 in combination c, plus 1.5. The to point is set to the x-coordinate of the apparent point of the bounding box center of the specific instance of obj4 in combination c in combination b, plus 2. Both obj7 and obj8 move from from to to, ending up the same relative distance from each other.The other shortened commands are similar.

  By splitting the larger command, an interesting detail was revealed. In the larger command, every point was set explicityly, so none defaulted. In the first shortened command, the y and z from values default to the bounding box center of obj7. Since the y and z to values default to the values set by from, neither obj7 nor obj8 will move in the y or z axes.

## BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>, or via the "cadbug.sh" script.