Metadata-Version: 2.4
Name: adxc
Version: 0.1.0
Summary: Create cell files for AdaOne
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: blackboxprotobuf>=1.0.1
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# adxc

`adxc` is a small Python library for creating AdaOne cell definition files (`.adxc`) and zipped cell packages (`.adxczip`). It makes it easy to define a robot cell programmatically: select a robot, add external equipment, create workframes, attach heads, and add cell elements such as fixtures or process parts.

The library is centered on the `Cell` object, which stores the robot, equipment, workframes, kinematics, and resources needed for a complete cell definition.

## Features

- Add a robot to a cell with `Cell.add_robot()`
- Add linear tracks and other external axes with `Cell.add_track()`
- Add gantry and positioner equipment
- Create named workframes and work offsets
- Attach tool heads and toolframes
- Add cell elements with mesh file references and optional workframe placement
- Save the result as a `.adxc` file or bundled `.adxczip` archive

## Usage

```python
from pathlib import Path
import adxc
from adxc import Cell, Robot, Track, Process

cell = Cell(name="Example")

cell.add_robot(Robot.Comau.NJ165_30)
cell.add_track(Track.VanSichen.Comau(length=4000, rotation=90, riser=0))

cell.add_head(
    model="Extruder",
    filepath=Path("meshes/Extruder.stl").resolve()
).add_toolframe(
    name="TCP1",
    process=Process.PELLET,
    translation=[100, 200, 300],
    rotation=[0, 0, 0]
)

cell.add_workframe(
    name="G54",
    translation=[1000, -1000, 340],
    rotation=[0, 0, 90],
    min_x=0, min_y=0, max_x=2000, max_y=4000,
    grid_spacing=100,
    workoffset_index=1,
)

cell.add_element(
    name="Printbed",
    translation=[1000, -1000, 340],
    rotation=[0, 0, 90],
    workframe=cell.work_frames[1],
    filepath=Path("meshes/Printbed.stl").resolve(),
)

adxc.save(cell, "output")
# or: adxc.savezip(cell, "output")
```

This creates a simple robot cell with a linear track, a process head, a workframe definition, and a physical element placed in the cell.

## Equipment types

The library exposes convenience methods for the main equipment categories used in robot cells:

- `add_robot(robot)`: Adds a robot model (from `Robot` enum) and its default home position, kinematic chain, and work offsets.
- `add_track(track)`: Adds a linear motion axis or rail (from `Track` enum). This is the method for linear equipment attached to the robot or cell.
- `add_gantry(gantry)`: Adds a gantry-style equipment unit (from `Gantry` enum), typically used for multi-axis motion or large work envelopes.
- `add_positioner(positioner)`: Adds a rotating or positioning table (from `Positioner` enum), often used for workpiece orientation or part handling.

Equipment types are accessed through enums (e.g., `Robot.Comau.NJ165_30`, `Track.VanSichen.Comau()`) and support named parameters for configuration. These methods insert equipment into the cell and also register any required external-axis kinematics so the robot and attached motion devices are represented consistently in the exported cell definition.

## Workframes

A workframe is a named coordinate system in the cell. Workframes are used to define where robot motion is relative to the fixture, machine, or workpiece. In `adxc`, each workframe has a name, translation, rotation, and optional limits for the grid used by the controller.

`Cell.add_workframe()` creates a new workframe and can assign it to a specific work offset index such as `G54`, `G55`, and so on (workoffset_index 1-4 for G54-G57, 5-24 for G505-G524). Grid parameters like `min_x`, `min_y`, `max_x`, `max_y`, and `grid_spacing` can be optionally specified to define motion boundaries. The first workframe is treated as the default cell work object, while additional workframes represent additional aligned coordinate systems.

## Cell elements

A cell element is a physical item in the cell, such as a machine bed, fixture, conveyor component, or other object that should be positioned in the same coordinate system as the robot. These are represented with `CellElement` objects and are typically given a name, filepath (for an STL or mesh), translation, rotation, and an optional workframe reference.

`Cell.add_element()` is the normal way to create these objects and attach them to the cell.

## Heads

A head represents the process tool or end-effector mounted on the robot. It can include the TCP definition, payload, file path to the tool geometry, and one or more `toolframes` describing tool offsets. `Cell.add_head()` registers the head on the robot with an optional `model` name, and `Head.add_toolframe()` adds tool definitions such as a TCP frame or process-specific tool orientation.

Toolframes support a `process` parameter (from the `Process` enum) to specify the type of process the tool performs, such as `Process.PELLET` for extrusion or other predefined processes.

Heads are important because they describe how the robot interacts with the workpiece or process, not just the robot body itself.

## Saving a cell

After the cell is assembled, you can save it to disk using the module-level `save()` and `savezip()` functions:

```python
adxc.save(cell, "output_dir")
adxc.savezip(cell, "output_dir")
```

`save()` writes a `.adxc` cell file. `savezip()` packages the cell and any referenced resource files into a `.adxczip` archive.

## Project status

This repository is made by reverse engineering .adxc files. Properties may difffer from actual implementation. Equipment GUIDs are created by reading cells created using AdaOne.
