Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

* Refactored proto definitions from 31 separate files into three organized files (`geometry.proto`, `datastructures.proto`, `message.proto`) to better reflect COMPAS package structure.

### Removed


Expand Down
71 changes: 46 additions & 25 deletions docs/missing_compas_type.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,59 +7,80 @@ This guide explains how to extend compas_pb with support for more COMPAS types.

## Creating New Serializers

### 1. Create a protobuf definition for the type you wish to add (for example `Circle`)
### 1. Add a protobuf definition for the type you wish to add

Create a protobuf definition for the new type you wish to add. This should be placed in `IDL/compas_pb/generated/`.
Add a protobuf message definition for the new type to the appropriate proto file:

```protobuf title="IDL/compas_pb/generated/custom_point.proto"
syntax = "proto3";
- **`geometry.proto`** - For geometry primitives (points, vectors, curves, surfaces, transformations)
- **`datastructures.proto`** - For COMPAS datastructures (mesh, polyhedron)
- **`message.proto`** - For serialization framework types (internal use only)

package compas_pb.data;
For example, to add a custom geometry type, add it to `src/compas_pb/protobuf_defs/compas_pb/generated/geometry.proto`:

import "compas_pb/generated/frame.proto";
```protobuf title="src/compas_pb/protobuf_defs/compas_pb/generated/geometry.proto"
// Add to the appropriate section in geometry.proto

message CircleData {
message CustomShapeData {
string guid = 1;
string name = 2;
float radius = 3;
FrameData frame = 4;
}
```

### 3. Generate the python code for the new type
Or, for a COMPAS datastructure type, add it to `src/compas_pb/protobuf_defs/compas_pb/generated/datastructures.proto`:

Now run the following command to generate the python code:
```protobuf title="src/compas_pb/protobuf_defs/compas_pb/generated/datastructures.proto"
// Import geometry types if needed
import "compas_pb/generated/geometry.proto";

message CustomDataStructureData {
string guid = 1;
string name = 2;
repeated PointData vertices = 3;
}
```

!!! note
Proto definitions are organized to match COMPAS package structure:
- `geometry.proto` → `compas.geometry`
- `datastructures.proto` → `compas.datastructures`
- `message.proto` → internal serialization framework

### 2. Generate the python code for the updated proto file

Now run the following command to regenerate the python code from the updated proto files:

```bash
invoke protobuf.generate-proto-classes -t python
invoke generate-proto-classes -t python
```

A new module called `circle_pb2` should now be available in `compas_pb/generated/`.
The generated modules (`geometry_pb2`, `datastructures_pb2`, `message_pb2`) in `src/compas_pb/generated/` will now include your new type.

### 4. Create a (de)serializer for the new type
### 3. Create a (de)serializer for the new type

To create a (de)serializer for a custom type, use the `@pb_serializer` and `@pb_deserializer` decorators. These decorators will be used to register the serializer and deserializer with the plugin system.

```python title="compas_pb/conversions.py"
from compas_pb.data import pb_serializer
from compas_pb.data import pb_deserializer
from compas_pb.generated import circle_pb2
from compas_pb.registry import pb_serializer
from compas_pb.registry import pb_deserializer
from compas_pb.generated import geometry_pb2 # or datastructures_pb2


@pb_serializer(Circle)
def my_circle_to_pb(obj: Circle) -> circle_pb2.CircleData:
"""Convert Circle to protobuf message."""
result = circle_pb2.CircleData()
result.guid = obj.guid
@pb_serializer(CustomShape)
def custom_shape_to_pb(obj: CustomShape) -> geometry_pb2.CustomShapeData:
"""Convert CustomShape to protobuf message."""
result = geometry_pb2.CustomShapeData()
result.guid = str(obj.guid)
result.name = obj.name
result.radius = obj.radius
result.frame = frame_to_pb(obj.frame)
result.frame.CopyFrom(frame_to_pb(obj.frame))
return result

@pb_deserializer(circle_pb2.CircleData)
def my_circle_from_pb(proto_data: circle_pb2.CircleData) -> Circle:
"""Convert protobuf message to Circle."""
return Circle(
@pb_deserializer(geometry_pb2.CustomShapeData)
def custom_shape_from_pb(proto_data: geometry_pb2.CustomShapeData) -> CustomShape:
"""Convert protobuf message to CustomShape."""
return CustomShape(
guid=proto_data.guid,
name=proto_data.name,
radius=proto_data.radius,
Expand Down
Loading