# Box

*A box is a rectangular prism defined by its center point and size (dimensions). Boxes can be oriented in three-dimensional space using one of two transformation methods.*

## Available Options

| *Option* | *Description* | *Applicable* |
|----------|---------------|--------------|
| [**Name**](#name) | Identifier for the box | always |
| [**Center**](#center) | Three-dimensional coordinates of the center point | always |
| [**Size**](#size) | Dimensions of the box (length, width, height) | always |
| [**Transform methods**](#transform-methods) | Method of defining the box orientation | always | 
| [**Axes**](#axes) | Two orthogonal vectors defining orientation | **Transform methods** is `Principal Axes` |
| [**Axis of rotation**](#axis-of-rotation) | Rotation axis vector | **Transform methods** is `Axis & Angle` |
| [**Angle of rotation**](#angle-of-rotation) | Rotation angle around the axis | **Transform methods** is `Axis & Angle` |


## Detailed Descriptions

### Name

*Identifier for the box volume entity.*

- **Required**
>**Note:** Names are not required to be unique, but using descriptive unique names is recommended for clarity.

### Center

*Three-dimensional coordinates (X, Y, Z) defining the center point of the box.*

- **Required**
- **Units:** Length

### Size

*Three-dimensional dimensions (length, width, height) of the box along its principal axes.*

- **Required**
- **Units:** Length
>**Note:** The size corresponds to the full extent along each axis, not half-lengths.

---

### Transform methods

Boxes can be oriented in three-dimensional space using one of two methods:

#### Axes

*Defines the box orientation using two orthogonal vectors.*

- **Required** (when using this method)
>**Notes:**
>  - The two axes must be orthogonal (perpendicular) to each other
>  - First axis (row 1) defines the primary direction (aligns with size X)
>  - Second axis (row 2) defines the secondary direction (aligns with size Y)
>  - Third axis is automatically computed to complete the right-handed coordinate system

#### Axis & Angle

*Defines the box orientation using a rotation axis and angle from the default orientation.*

##### Axis of rotation

*The axis vector (X, Y, Z) around which the box is rotated.*

- **Default:** `(0, 0, 1)`
>**Note:** The axis is normalized internally.

##### Angle of rotation

*The angle of rotation around the specified axis.*

- **Default:** `0 degrees`
- **Units:** Angle
>**Note:** Positive angles follow the right-hand rule around the rotation axis.

---

<details>
<summary><h3 style="display:inline-block"> 💡 Tips</h3></summary>

- Use boxes for rectangular refinement zones in wakes or regions of interest
- Align the box with the expected flow direction for wake capture
- For rotated boxes, the Principal Axes method provides more intuitive control
- Consider using multiple overlapping boxes for complex L-shaped or T-shaped regions

</details>

---

<details>
<summary><h3 style="display:inline-block"> ❓ Frequently Asked Questions</h3></summary>

- **What happens if I don't specify orientation?**
  > The box will align with the global coordinate system axes (no rotation).

- **Can I resize a box after creation?**
  > Yes, you can modify the size parameters at any time before meshing.

- **How do the axes relate to the size dimensions?**
  > The first axis corresponds to size[0], the second axis to size[1], and the computed third axis to size[2].

</details>

---

<details>
<summary><h3 style="display:inline-block"> 🐍 Python Example Usage</h3></summary>

```python
import flow360 as fl

# Box using axis and angle rotation
box = fl.Box(
    name="wake_region",
    center=(2, 0, 0) * fl.u.m,
    size=(4, 1, 1) * fl.u.m,
    axis_of_rotation=(0, 1, 0),
    angle_of_rotation=15 * fl.u.deg
)

# Box using principal axes
box_axes = fl.Box.from_principal_axes(
    name="refinement_box",
    center=(0, 0, 0) * fl.u.m,
    size=(2, 1, 0.5) * fl.u.m,
    axes=[(1, 0, 0), (0, 1, 0)]
)
```

</details>