'\" t
.\"     Title: EDIT TRANSLATE
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 08/28/2023
.\"    Manual: BRL-CAD User Commands
.\"    Source: BRL-CAD
.\"  Language: English
.\"
.TH "EDIT TRANSLATE" "nged" "08/28/2023" "BRL\-CAD" "BRL\-CAD User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
edit_translate \- Translates the positions of \fIobject\fRs, using coordinates, offsets, and objects as reference points\&.
.SH "SYNOPSIS"
.HP \w'\fBedit\ translate\fR\ 'u
\fBedit translate\fR [(1)\ \fIfrom\fR] (2)\ \fIto\fR \fIobject\fR...
.br

.br

.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.HP \w'(1)\ 'u
(1)\ [\fB\-n\fR] \fB\-k\fR {(4)\ \fIfrom_object\fR | (3)\ \fIfrom_position\fR}
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.HP \w'(2)\ 'u
(2)\ [\fB\-n\fR] [\fB\-a\fR | \fB\-r\fR] {(4)\ \fIto_object\fR | (3)\ \fIto_position\fR}
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.HP \w'(3)\ 'u
(3)\ {(5)\ \fIcoords\fR} | {[\ \fB\-x\fR\ {\fIx\fR\ |\ (4)\ \fIx\-obj\fR\ }\ ]\ [\ \fB\-y\fR\ {\fIy\fR\ |\ (4)\ \fIy\-obj\fR\ }\ ]\ [\ \fB\-z\fR\ {\fIz\fR\ |\ (4)\ \fIz\-obj\fR\ }\ ]} 
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.HP \w'(4)\ 'u
(4)\ [\fIpath/\fR]\ \fIobject\fR  [(5)\ \fIoffset_distance\fR]
.HP \w'(5)\ 'u
(5)\ \fIx\fR [\fIy\fR\ [\fIz\fR]]
.SH "DESCRIPTION"
.PP
Used to move one or more instances of primitive or combination objects\&. The positions of
\fIobject\fR\*(Aqs are translated from
\fIfrom\fR
to
\fIto\fR\&.
.PP
See the
\fBedit\fR
command\*(Aqs manual for more information\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \& A not particularly useful demonstration of the command's capabilities.\fR
.PP
> \fBedit translate \-k 0 0 0 \-a \&. obj1 obj2 obj3 obj4 obj5\fR
.RS 4
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\&.
.RE
.PP
\fBExample\ \&2.\ \&Move several objects together.\fR
.PP
> \fB edit translate \-a \-z obj1 obj2 obj3 obj4 obj5 \fR
.RS 4
The
\fIfrom\fR
point defaults to the bounding box center of the first target
\fIobject\fR, which is obj2\&. Every instance of objects obj2 \- obj5 is moved
\fIfrom\fR
obj2
\fIto\fR
the z\-axis of obj1\&. If the z\-coordinate of
\fIfrom\fR
was 7, and the z\-coordinate of
\fIto\fR
was 5, then each object would move \-2 units in the z\-axis\&.
.RE
.PP
\fBExample\ \&3.\ \&Align several objects to the same point on an axis.\fR
.PP
> \fB edit translate \-k \&. \-a \-z obj1 obj2 obj3 obj4 obj5 \fR
.RS 4
Sets the elevation of obj[2\-5] to the elevation of obj1\&. Each object uses its own bounding box center as the
\fIfrom\fR
point in an operation that moves
\fIto\fR
the bounding box center of obj1\&.
.RE
.PP
\fBExample\ \&4.\ \&Move several objects to the same point.\fR
.PP
> \fB edit translate \-k \&. \-a obj1 obj2 obj3 obj4 obj5 \fR
.RS 4
Each object uses its own bounding box center as the
\fIfrom\fR
point in an operation that moves
\fIto\fR
the bounding box center of obj1\&. All
\fIobject\fRs end up centered on obj2\&.
.RE
.PP
\fBExample\ \&5.\ \&Explicitly set the z-axis of an obj.\fR
.PP
> \fBedit translate \-a \-z 7\&.8 obj\fR
.RS 4
Moves obj
\fIfrom\fR
its bounding box center
\fIto\fR
7\&.8 on the z\-axis\&.
.RE
.PP
\fBExample\ \&6.\ \&Move several objects from their own natural origins to their own bounding box centers.\fR
.PP
> \fBedit translate \-n \-k \&. \-a \&. obj1 obj2 obj3\fR
.RS 4
The
\fIobject\fRs are moved from their own natural origins to their own bounding box centers\&.
.RE
.PP
\fBExample\ \&7.\ \& Set the z-axis of the center of one object to the z-axis of the natural origin of another object.\fR
.PP
> \fBedit translate \-n \-a \-z obj2/obj3 obj1\fR
.RS 4
Moves obj1 up or down
\fIfrom\fR
the elevation of its bounding box center
\fIto\fR
the apparent elevation of the natural origin of the instance of obj3 in obj2\&.
.RE
.PP
\fBExample\ \&8.\ \& Same result as above, but moving \fIfrom\fR the natural origin of obj1 rather than its bounding box center.\fR
.PP
> \fB edit translate \-n \-k obj1 \-n \-a \-z obj2/obj3 obj1 \fR
.RS 4
.RE
.PP
> \fBedit translate \-n \-k \&. \-n \-a \-z obj2/obj3 obj1\fR
.RS 4
.RE
.PP
\fBExample\ \&9.\ \& The use of \fIobject\fR paths and individual coordinate specifiers.\fR
.PP
> \fBedit translate \-a \-x 8 \-z 42 obj1/obj2/obj3\fR
.RS 4
Moves the instance of ob3 in obj2
\fIfrom\fR
the apparent bounding box center of obj3
\fIas offset by\fR
obj1/obj2,
\fIto\fR
x=8, z=42, without moving in the y\-axis\&. Note that this is not the same as
\fB\-a 8 0 42\fR\&. 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\&.
.RE
.PP
\fBExample\ \&10.\ \&Translations using relative positions.\fR
.PP
> \fBedit translate \-k obj1 \-r \-z 5 obj2\fR
.RS 4
.RE
.PP
> \fBedit translate \-a \-z obj1 0 0 5 obj2\fR
.RS 4
.RE
.PP
.RS 4
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
\fIplus 5 units\fR\&.
.RE
.PP
\fBExample\ \&11.\ \& This example breaks down a particularly complex translation.\fR
.PP
> \fB 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 \fR
.RS 4
Every use of
\fBtranslate\fR
involves a
\fIfrom\fR
point and a
\fIto\fR
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:
.RE
.PP
> \fB edit translate \-k \-x c/obj1 1\&.5 \-a \-x b/c/obj4 2 obj7 obj8 \fR
.RS 4
.RE
.PP
> \fB edit translate \-k \-y c/obj2 0 3 \-a \-y b/c/obj5 0 4 obj7 obj8 \fR
.RS 4
.RE
.PP
> \fB edit translate \-k \-z c/obj3 0 0 10 \-a \-z b/c/obj6 0 0 20 obj7 obj8 \fR
.RS 4
In the first shortened command, the
\fIfrom\fR
point is set to the x\-coordinate of the apparent point of the bounding box center of the instance of obj1 in combination c,
\fIplus 1\&.5\fR\&. The
\fIto\fR
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,
\fIplus 2\fR\&. Both obj7 and obj8 move from
\fIfrom\fR
to
\fIto\fR, ending up the same relative distance from each other\&.The other shortened commands are similar\&.
.sp
By splitting the larger command, an interesting detail was revealed\&. In the larger command, every point was set explicitly, so none defaulted\&. In the first shortened command, the
\fIy\fR
and
\fIz\fR
\fIfrom\fR
values default to the bounding box center of obj7\&. Since the
\fIy\fR
and
\fIz\fR
\fIto\fR
values default to the values set by
\fIfrom\fR, neither obj7 nor obj8 will move in the
\fIy\fR
or
\fIz\fR
axes\&.
.RE
.SH "AUTHOR"
.PP
BRL\-CAD Team
.SH "BUG REPORTS"
.PP
Reports of bugs or problems should be submitted via electronic mail to
devs@brlcad\&.org
