mirror of
https://github.com/gumyr/build123d.git
synced 2025-12-06 02:30:55 -08:00
130 lines
3.6 KiB
ReStructuredText
130 lines
3.6 KiB
ReStructuredText
Moving Objects
|
|
==============
|
|
|
|
In build123d, there are several methods to move objects. These methods vary
|
|
based on the mode of operation and provide flexibility for object placement
|
|
and orientation. Below, we outline the three main approaches to moving objects:
|
|
builder mode, algebra mode, and direct manipulation methods.
|
|
|
|
Builder Mode
|
|
------------
|
|
In builder mode, object locations are defined before the objects themselves are
|
|
created. This approach ensures that objects are positioned correctly during the
|
|
construction process. The following tools are commonly used to specify locations:
|
|
|
|
1. :class:`~build_common.Locations` Use this to define a specific location for the objects within the `with` block.
|
|
2. :class:`~build_common.GridLocations` Arrange objects in a grid pattern.
|
|
3. :class:`~build_common.PolarLocations` Position objects in a circular pattern.
|
|
4. :class:`~build_common.HexLocations` Arrange objects in a hexagonal grid.
|
|
|
|
.. note::
|
|
The location(s) of an object must be defined prior to its creation when using builder mode.
|
|
|
|
Example:
|
|
|
|
.. code-block:: python
|
|
|
|
with Locations((10, 20, 30)):
|
|
Box(5, 5, 5)
|
|
|
|
Algebra Mode
|
|
------------
|
|
In algebra mode, object movement is expressed using algebraic operations. The
|
|
:class:`~geometry.Pos` function, short for Position, represents a location, which can be combined
|
|
with objects or planes to define placement.
|
|
|
|
1. ``Pos() * shape``: Applies a position to a shape.
|
|
2. ``Plane() * Pos() * shape``: Combines a plane with a position and applies it to a shape.
|
|
|
|
Rotation is an important concept in this mode. A :class:`~geometry.Rotation` represents a location
|
|
with orientation values set, which can be used to define a new location or modify
|
|
an existing one.
|
|
|
|
Example:
|
|
|
|
.. code-block:: python
|
|
|
|
rotated_box = Rotation(45, 0, 0) * box
|
|
|
|
Direct Manipulation Methods
|
|
---------------------------
|
|
The following methods allow for direct manipulation of a shape's location and orientation
|
|
after it has been created. These methods offer a mix of absolute and relative transformations.
|
|
|
|
Position
|
|
^^^^^^^^
|
|
- **Absolute Position:** Set the position directly.
|
|
|
|
.. code-block:: python
|
|
|
|
shape.position = (x, y, z)
|
|
|
|
- **Relative Position:** Adjust the position incrementally.
|
|
|
|
.. code-block:: python
|
|
|
|
shape.position += (x, y, z)
|
|
shape.position -= (x, y, z)
|
|
|
|
|
|
Orientation
|
|
^^^^^^^^^^^
|
|
- **Absolute Orientation:** Set the orientation directly.
|
|
|
|
.. code-block:: python
|
|
|
|
shape.orientation = (X, Y, Z)
|
|
|
|
- **Relative Orientation:** Adjust the orientation incrementally.
|
|
|
|
.. code-block:: python
|
|
|
|
shape.orientation += (X, Y, Z)
|
|
shape.orientation -= (X, Y, Z)
|
|
|
|
Movement Methods
|
|
^^^^^^^^^^^^^^^^
|
|
- **Relative Move:**
|
|
|
|
.. code-block:: python
|
|
|
|
shape.move(Location)
|
|
|
|
- **Relative Move of Copy:**
|
|
|
|
.. code-block:: python
|
|
|
|
relocated_shape = shape.moved(Location)
|
|
|
|
- **Absolute Move:**
|
|
|
|
.. code-block:: python
|
|
|
|
shape.locate(Location)
|
|
|
|
- **Absolute Move of Copy:**
|
|
|
|
.. code-block:: python
|
|
|
|
relocated_shape = shape.located(Location)
|
|
|
|
|
|
Transformation a.k.a. Translation and Rotation
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. note::
|
|
These methods don't work in the same way as the previous methods in that they don't just change
|
|
the object's internal :class:`~geometry.Location` but transform the base object itself which
|
|
is quite slow and potentially problematic.
|
|
|
|
- **Translation:** Move a shape relative to its current position.
|
|
|
|
.. code-block:: python
|
|
|
|
relocated_shape = shape.translate(x, y, z)
|
|
|
|
- **Rotation:** Rotate a shape around a specified axis by a given angle.
|
|
|
|
.. code-block:: python
|
|
|
|
rotated_shape = shape.rotate(Axis, angle_in_degrees)
|