mirror of
https://github.com/dptech-corp/Uni-Lab-OS.git
synced 2025-12-17 04:51:10 +00:00
406 lines
12 KiB
Markdown
406 lines
12 KiB
Markdown
# 物料构建指南
|
||
|
||
## 概述
|
||
|
||
在UniLab-OS系统中，任何工作站中所需要用到的物料主要包括四个核心组件：
|
||
|
||
1. **桌子（Deck）** - 工作台面，定义整个工作空间的布局
|
||
2. **堆栈（Warehouse）** - 存储区域，用于放置载具和物料
|
||
3. **载具（Carriers）** - 承载瓶子等物料的容器架
|
||
4. **瓶子（Bottles）** - 实际的物料容器
|
||
|
||
本文档以BioYond工作站为例，详细说明如何构建这些物料组件。
|
||
|
||
## 文件结构
|
||
|
||
物料定义文件位于 `unilabos/resources/` 文件夹中：
|
||
|
||
```
|
||
unilabos/resources/bioyond/
|
||
├── decks.py # 桌子定义
|
||
├── YB_warehouses.py # 堆栈定义
|
||
├── YB_bottle_carriers.py # 载具定义
|
||
└── YB_bottles.py # 瓶子定义
|
||
```
|
||
|
||
对应的注册表文件位于 `unilabos/registry/resources/bioyond/` 文件夹中：
|
||
|
||
```
|
||
unilabos/registry/resources/bioyond/
|
||
├── deck.yaml # 桌子注册表
|
||
├── YB_bottle_carriers.yaml # 载具注册表
|
||
└── YB_bottle.yaml # 瓶子注册表
|
||
```
|
||
|
||
## 1. 桌子（Deck）构建
|
||
|
||
桌子是整个工作站的基础，定义了工作空间的尺寸和各个组件的位置。
|
||
|
||
### 代码示例 (decks.py)
|
||
|
||
```python
|
||
from pylabrobot.resources import Coordinate, Deck
|
||
from unilabos.resources.bioyond.YB_warehouses import (
|
||
bioyond_warehouse_2x2x1,
|
||
bioyond_warehouse_3x5x1,
|
||
bioyond_warehouse_20x1x1,
|
||
bioyond_warehouse_3x3x1,
|
||
bioyond_warehouse_10x1x1
|
||
)
|
||
|
||
class BIOYOND_YB_Deck(Deck):
|
||
def __init__(
|
||
self,
|
||
name: str = "YB_Deck",
|
||
size_x: float = 4150, # 桌子X方向尺寸 (mm)
|
||
size_y: float = 1400.0, # 桌子Y方向尺寸 (mm)
|
||
size_z: float = 2670.0, # 桌子Z方向尺寸 (mm)
|
||
category: str = "deck",
|
||
setup: bool = False
|
||
) -> None:
|
||
super().__init__(name=name, size_x=4150.0, size_y=1400.0, size_z=2670.0)
|
||
if setup:
|
||
self.setup() # 当在工作站配置中setup为True时，自动创建并放置所有预定义的堆栈
|
||
|
||
def setup(self) -> None:
|
||
# 定义桌子上的各个仓库区域
|
||
self.warehouses = {
|
||
"自动堆栈-左": bioyond_warehouse_2x2x1("自动堆栈-左"),
|
||
"自动堆栈-右": bioyond_warehouse_2x2x1("自动堆栈-右"),
|
||
"手动堆栈-左": bioyond_warehouse_3x5x1("手动堆栈-左"),
|
||
"手动堆栈-右": bioyond_warehouse_3x5x1("手动堆栈-右"),
|
||
"粉末加样头堆栈": bioyond_warehouse_20x1x1("粉末加样头堆栈"),
|
||
"配液站内试剂仓库": bioyond_warehouse_3x3x1("配液站内试剂仓库"),
|
||
"试剂替换仓库": bioyond_warehouse_10x1x1("试剂替换仓库"),
|
||
}
|
||
|
||
# 定义各个仓库在桌子上的坐标位置
|
||
self.warehouse_locations = {
|
||
"自动堆栈-左": Coordinate(-100.3, 171.5, 0.0),
|
||
"自动堆栈-右": Coordinate(3960.1, 155.9, 0.0),
|
||
"手动堆栈-左": Coordinate(-213.3, 804.4, 0.0),
|
||
"手动堆栈-右": Coordinate(3960.1, 807.6, 0.0),
|
||
"粉末加样头堆栈": Coordinate(415.0, 1301.0, 0.0),
|
||
"配液站内试剂仓库": Coordinate(2162.0, 437.0, 0.0),
|
||
"试剂替换仓库": Coordinate(1173.0, 802.0, 0.0),
|
||
}
|
||
|
||
# 将仓库分配到桌子的指定位置
|
||
for warehouse_name, warehouse in self.warehouses.items():
|
||
self.assign_child_resource(warehouse, location=self.warehouse_locations[warehouse_name])
|
||
```
|
||
|
||
### 在工作站配置中的使用
|
||
|
||
当在工作站配置文件中定义桌子时，可以通过`setup`参数控制是否自动建立所有堆栈：
|
||
|
||
```json
|
||
{
|
||
"id": "YB_Bioyond_Deck",
|
||
"name": "YB_Bioyond_Deck",
|
||
"children": [],
|
||
"parent": "bioyond_cell_workstation",
|
||
"type": "deck",
|
||
"class": "BIOYOND_YB_Deck",
|
||
"config": {
|
||
"type": "BIOYOND_YB_Deck",
|
||
"setup": true
|
||
},
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**重要说明**：
|
||
- 当 `"setup": true` 时，系统会自动调用桌子的 `setup()` 方法
|
||
- 这将创建并放置所有预定义的堆栈到桌子上的指定位置
|
||
- 如果 `"setup": false` 或省略该参数，则只创建空桌子，需要手动添加堆栈
|
||
|
||
### 关键要点注释
|
||
|
||
- `size_x`, `size_y`, `size_z`: 定义桌子的物理尺寸
|
||
- `warehouses`: 字典类型，包含桌子上所有的仓库区域
|
||
- `warehouse_locations`: 定义每个仓库在桌子坐标系中的位置
|
||
- `assign_child_resource()`: 将仓库资源分配到桌子的指定位置
|
||
- `setup()`: 可选的自动设置方法，初始化时可调用
|
||
|
||
## 2. 堆栈（Warehouse）构建
|
||
|
||
堆栈定义了存储区域的规格和布局，用于放置载具。
|
||
|
||
### 代码示例 (YB_warehouses.py)
|
||
|
||
```python
|
||
from unilabos.resources.warehouse import WareHouse, YB_warehouse_factory
|
||
|
||
def bioyond_warehouse_1x4x4(name: str) -> WareHouse:
|
||
"""创建BioYond 1x4x4仓库
|
||
|
||
Args:
|
||
name: 仓库名称
|
||
|
||
Returns:
|
||
WareHouse: 仓库对象
|
||
"""
|
||
return YB_warehouse_factory(
|
||
name=name,
|
||
num_items_x=1, # X方向位置数量
|
||
num_items_y=4, # Y方向位置数量
|
||
num_items_z=4, # Z方向位置数量（层数）
|
||
dx=10.0, # X方向起始偏移
|
||
dy=10.0, # Y方向起始偏移
|
||
dz=10.0, # Z方向起始偏移
|
||
item_dx=137.0, # X方向间距
|
||
item_dy=96.0, # Y方向间距
|
||
item_dz=120.0, # Z方向间距（层高）
|
||
category="warehouse",
|
||
)
|
||
|
||
def bioyond_warehouse_2x2x1(name: str) -> WareHouse:
|
||
"""创建BioYond 2x2x1仓库（自动堆栈）"""
|
||
return YB_warehouse_factory(
|
||
name=name,
|
||
num_items_x=2,
|
||
num_items_y=2,
|
||
num_items_z=1, # 单层
|
||
dx=10.0,
|
||
dy=10.0,
|
||
dz=10.0,
|
||
item_dx=137.0,
|
||
item_dy=96.0,
|
||
item_dz=120.0,
|
||
category="YB_warehouse",
|
||
)
|
||
```
|
||
|
||
### 关键要点注释
|
||
|
||
- `num_items_x/y/z`: 定义仓库在各个方向的位置数量
|
||
- `dx/dy/dz`: 第一个位置的起始偏移坐标
|
||
- `item_dx/dy/dz`: 相邻位置之间的间距
|
||
- `category`: 仓库类别，用于分类管理
|
||
- `YB_warehouse_factory`: 统一的仓库创建工厂函数
|
||
|
||
## 3. 载具（Carriers）构建
|
||
|
||
载具是承载瓶子的容器架，定义了瓶子的排列方式和位置。
|
||
|
||
### 代码示例 (YB_bottle_carriers.py)
|
||
|
||
```python
|
||
from pylabrobot.resources import create_homogeneous_resources, Coordinate, ResourceHolder, create_ordered_items_2d
|
||
from unilabos.resources.itemized_carrier import Bottle, BottleCarrier
|
||
from unilabos.resources.bioyond.YB_bottles import YB_pei_ye_xiao_Bottle
|
||
|
||
def YB_peiyepingxiaoban(name: str) -> BottleCarrier:
|
||
"""配液瓶(小)板 - 4x2布局，8个位置
|
||
|
||
Args:
|
||
name: 载具名称
|
||
|
||
Returns:
|
||
BottleCarrier: 载具对象，包含8个配液瓶位置
|
||
"""
|
||
|
||
# 载具物理尺寸 (mm)
|
||
carrier_size_x = 127.8
|
||
carrier_size_y = 85.5
|
||
carrier_size_z = 65.0
|
||
|
||
# 瓶位参数
|
||
bottle_diameter = 35.0 # 瓶子直径
|
||
bottle_spacing_x = 42.0 # X方向瓶子间距
|
||
bottle_spacing_y = 35.0 # Y方向瓶子间距
|
||
|
||
# 计算起始位置 (居中排列)
|
||
start_x = (carrier_size_x - (4 - 1) * bottle_spacing_x - bottle_diameter) / 2
|
||
start_y = (carrier_size_y - (2 - 1) * bottle_spacing_y - bottle_diameter) / 2
|
||
|
||
# 创建瓶位布局：4列x2行
|
||
sites = create_ordered_items_2d(
|
||
klass=ResourceHolder,
|
||
num_items_x=4, # 4列
|
||
num_items_y=2, # 2行
|
||
dx=start_x,
|
||
dy=start_y,
|
||
dz=5.0, # 瓶子底部高度
|
||
item_dx=bottle_spacing_x,
|
||
item_dy=bottle_spacing_y,
|
||
size_x=bottle_diameter,
|
||
size_y=bottle_diameter,
|
||
size_z=carrier_size_z,
|
||
)
|
||
|
||
# 为每个瓶位设置名称
|
||
for k, v in sites.items():
|
||
v.name = f"{name}_{v.name}"
|
||
|
||
# 创建载具对象
|
||
carrier = BottleCarrier(
|
||
name=name,
|
||
size_x=carrier_size_x,
|
||
size_y=carrier_size_y,
|
||
size_z=carrier_size_z,
|
||
sites=sites,
|
||
model="YB_peiyepingxiaoban",
|
||
)
|
||
|
||
# 设置载具布局参数
|
||
carrier.num_items_x = 4
|
||
carrier.num_items_y = 2
|
||
carrier.num_items_z = 1
|
||
|
||
# 定义瓶子排列顺序
|
||
ordering = ["A1", "A2", "A3", "A4", "B1", "B2", "B3", "B4"]
|
||
|
||
# 为每个位置创建瓶子实例
|
||
for i in range(8):
|
||
carrier[i] = YB_pei_ye_xiao_Bottle(f"{name}_bottle_{ordering[i]}")
|
||
|
||
return carrier
|
||
```
|
||
|
||
### 关键要点注释
|
||
|
||
- `carrier_size_x/y/z`: 载具的物理尺寸
|
||
- `bottle_diameter`: 瓶子的直径，用于计算瓶位大小
|
||
- `bottle_spacing_x/y`: 瓶子之间的间距
|
||
- `create_ordered_items_2d`: 创建二维排列的瓶位
|
||
- `sites`: 瓶位字典，存储所有瓶子位置信息
|
||
- `ordering`: 定义瓶位的命名规则（如A1, A2, B1等）
|
||
|
||
## 4. 瓶子（Bottles）构建
|
||
|
||
瓶子是最终的物料容器，定义了容器的物理属性。
|
||
|
||
### 代码示例 (YB_bottles.py)
|
||
|
||
```python
|
||
from unilabos.resources.itemized_carrier import Bottle
|
||
|
||
def YB_pei_ye_xiao_Bottle(
|
||
name: str,
|
||
diameter: float = 35.0, # 瓶子直径 (mm)
|
||
height: float = 60.0, # 瓶子高度 (mm)
|
||
max_volume: float = 30000.0, # 最大容量 (μL) - 30mL
|
||
barcode: str = None, # 条码
|
||
) -> Bottle:
|
||
"""创建配液瓶(小)
|
||
|
||
Args:
|
||
name: 瓶子名称
|
||
diameter: 瓶子直径
|
||
height: 瓶子高度
|
||
max_volume: 最大容量（微升）
|
||
barcode: 条码标识
|
||
|
||
Returns:
|
||
Bottle: 瓶子对象
|
||
"""
|
||
return Bottle(
|
||
name=name,
|
||
diameter=diameter,
|
||
height=height,
|
||
max_volume=max_volume,
|
||
barcode=barcode,
|
||
model="YB_pei_ye_xiao_Bottle",
|
||
)
|
||
|
||
def YB_ye_Bottle(
|
||
name: str,
|
||
diameter: float = 40.0,
|
||
height: float = 70.0,
|
||
max_volume: float = 50000.0, # 最大容量
|
||
barcode: str = None,
|
||
) -> Bottle:
|
||
"""创建液体瓶"""
|
||
return Bottle(
|
||
name=name,
|
||
diameter=diameter,
|
||
height=height,
|
||
max_volume=max_volume,
|
||
barcode=barcode,
|
||
model="YB_ye_Bottle",
|
||
)
|
||
```
|
||
|
||
### 关键要点注释
|
||
|
||
- `diameter`: 瓶子直径，影响瓶位大小计算
|
||
- `height`: 瓶子高度，用于碰撞检测和移液计算
|
||
- `max_volume`: 最大容量，单位为微升（μL）
|
||
- `barcode`: 条码标识，用于瓶子追踪
|
||
- `model`: 型号标识，用于区分不同类型的瓶子
|
||
|
||
## 5. 注册表配置
|
||
|
||
创建完物料定义后，需要在注册表中注册这些物料，使系统能够识别和使用它们。
|
||
|
||
在 `unilabos/registry/resources/bioyond/` 目录下创建：
|
||
|
||
- `deck.yaml` - 桌子注册表
|
||
- `YB_bottle_carriers.yaml` - 载具注册表
|
||
- `YB_bottle.yaml` - 瓶子注册表
|
||
|
||
### 5.1 桌子注册表 (deck.yaml)
|
||
|
||
```yaml
|
||
BIOYOND_YB_Deck:
|
||
category:
|
||
- deck # 前端显示的分类存放
|
||
class:
|
||
module: unilabos.resources.bioyond.decks:BIOYOND_YB_Deck # 定义桌子的类的路径
|
||
type: pylabrobot
|
||
description: BIOYOND_YB_Deck # 描述信息
|
||
handles: []
|
||
icon: 配液站.webp # 图标文件
|
||
init_param_schema: {}
|
||
registry_type: resource # 注册类型
|
||
version: 1.0.0 # 版本号
|
||
```
|
||
|
||
### 5.2 载具注册表 (YB_bottle_carriers.yaml)
|
||
|
||
```yaml
|
||
YB_peiyepingxiaoban:
|
||
category:
|
||
- yb3
|
||
- YB_bottle_carriers
|
||
class:
|
||
module: unilabos.resources.bioyond.YB_bottle_carriers:YB_peiyepingxiaoban
|
||
type: pylabrobot
|
||
description: YB_peiyepingxiaoban
|
||
handles: []
|
||
icon: ''
|
||
init_param_schema: {}
|
||
registry_type: resource
|
||
version: 1.0.0
|
||
```
|
||
|
||
### 5.3 瓶子注册表 (YB_bottle.yaml)
|
||
|
||
```yaml
|
||
YB_pei_ye_xiao_Bottle:
|
||
category:
|
||
- yb3
|
||
- YB_bottle
|
||
class:
|
||
module: unilabos.resources.bioyond.YB_bottles:YB_pei_ye_xiao_Bottle
|
||
type: pylabrobot
|
||
description: YB_pei_ye_xiao_Bottle
|
||
handles: []
|
||
icon: ''
|
||
init_param_schema: {}
|
||
registry_type: resource
|
||
version: 1.0.0
|
||
```
|
||
|
||
### 注册表关键要点注释
|
||
|
||
- `category`: 物料分类，用于在云端（网页界面）中的分类中显示
|
||
- `module`: Python模块路径，格式为 `模块路径:类名`
|
||
- `type`: 框架类型，通常为 `pylabrobot`（默认即可）
|
||
- `description`: 描述信息，显示在用户界面中
|
||
- `icon`: （名称唯一自动匹配后端上传的图标文件名，显示在云端）
|
||
- `registry_type`: 固定为 `resource`
|
||
- `version`: 版本号，用于版本管理
|