# Packing Data Import/Export Guide

This guide details the CSV structures used to import package configurations into the 3D Bin Packing tool and to export the calculated packing layouts.

---

## 1. Importing Packages (CSV Structure)

You can import package sets directly from a CSV file. The file should contain a header row with the exact column names specified below.

> [!TIP]
> **AI-Assisted Import:** If your CSV uses different column names or a non-standard structure, the server will automatically use the **Google Gemini API** to intelligently restructure the data into the expected format. This requires a `GEMINI_API_KEY` environment variable to be configured (see `.env.example`). All dimensions in the CSV are expected to be in **centimeters (cm)**, regardless of the UI's active metric unit setting.

### Expected Columns

| Column Name | Data Type | Required? | Description |
| :--- | :--- | :--- | :--- |
| `name` | String | Yes | Name of the package (e.g., `Box-A`). |
| `shape` | String | Yes | Either `box` or `cylinder` (case-insensitive). |
| `quantity` | Integer | Yes | The number of copies of this item to place (between `1` and `20`). |
| `width_or_diameter` | Float | Yes | The width of the box, or the diameter of the cylinder (in centimeters). |
| `height` | Float | Yes | The height (vertical dimension) of the item (in centimeters). |
| `depth` | Float | No | The depth of the box (in centimeters). Can be left empty/blank for cylinders. |
| `rotation_lock` | String | No | Limits allowed rotations. **Optional field** (can be omitted or left blank). Options:<br>- `auto`: Decisions left to the algorithm (default).<br>- `0`: Locked standing flat (`W×H×D`).<br>- `1` through `5`: Fixed rotation states. |
| `required` | Boolean | No | **Optional field** (can be omitted or left blank). Mark as `true` to prioritize packing this item first, or `false` for standard priority (default). |

> [!NOTE]
> **Microsoft Excel Compatibility:** Prepend `sep=,` on the very first line of your CSV files. This tells Excel to use the comma as a delimiter automatically, preventing Excel from merging the values into a single column.

### Sample Import CSV File Contents

Create a file named `packages.csv` and paste the following template:

```csv
sep=,
name,shape,quantity,width_or_diameter,height,depth,rotation_lock,required
Large Box,box,5,250.0,200.0,100.0,auto,false
Required Cylinder,cylinder,2,10.0,200.0,,0,true
Standard Box,box,3,50.0,50.0,50.0,,
Flat Panel,box,1,120.0,80.0,10.0,,
```

---

## 2. Exporting Packing Layouts (CSV Structure)

When you calculate a packing layout and click **Export Results (CSV)**, the app compiles a CSV list detailing where each package copy was placed inside the container.

### Exported Columns

| Column Name | Description |
| :--- | :--- |
| `Name` | The unique copy identifier (e.g. `Large Box__1`, `Large Box__2`). |
| `Source Package` | The original package configuration name (`Large Box`). |
| `Shape` | The physical shape (`box` or `cylinder`). |
| `Status` | `Fitted` if placed inside the container, or `Unfitted` if it could not fit. |
| `Position X` | The starting coordinate on the horizontal Width axis (blank if unfitted). |
| `Position Y` | The starting coordinate on the vertical Height axis (blank if unfitted). |
| `Position Z` | The starting coordinate on the horizontal Depth axis (blank if unfitted). |
| `Rotated Width` | The actual packed width occupied by the item after rotation. |
| `Rotated Height` | The actual packed height occupied by the item after rotation. |
| `Rotated Depth` | The actual packed depth occupied by the item after rotation. |