Metadata-Version: 2.4
Name: adxc
Version: 0.1.3
Summary: Create cell files for AdaOne
Requires-Python: >=3.13
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.

## Post processor

`Cell.add_post_processor()` embeds an AdaOne post processor (`.adxp` file) in the cell and points every head at it:

```python
cell.add_post_processor("post.adxp")
```

The file is embedded unchanged and keeps the ID it carries (an ID is only generated if the file has none), so the post processor's contents are not interpreted by the library. Calling it again replaces the previous one.

## 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.
