.dna 转换方案
`.dna` 是 SnapGene 二进制格式。GenePad 读取和写出时仅使用 SnapGene 兼容 packet： 主序列、拓扑、features、primers、notes、碱基颜色，以及可解析的 chromatogram / ZTR 读段；比对读段等 GenePad 专有数据请保存到 `.gen` 或 `.gjson`。
Packet Model
二进制包结构
packet = packet_type: u8
+ payload_length: u32_be
+ payload: [u8; payload_length]| Packet | 名称 | 读取 | 写出 |
|---|---|---|---|
0x09 | Cookie | 验证 payload 前 8 字节为 SnapGene | 必须写出 |
0x00 | DNA | 读取 flags 和序列 | 必须写出 |
0x05 | Primers | 解析 primer XML | 有 primer 时写出 |
0x06 | Notes | 解析 accession、comments、date、organism | 建议写出 |
0x0a | Features | 解析 feature XML | 建议写出 |
0x14 | StrandColors | 解析正/反链碱基颜色 | 有 baseColorRanges 时写出 |
0x0b | ZTR read | 尝试提取内嵌测序读段 | 当前不写出 |
Mapping
字段映射
DNA packet 0x00主序列与 flags
| payload | 映射 |
|---|---|
payload[0] & 0x01 | isCircular |
payload[0] & 0x04 | isDoubleStranded |
payload[0] & 0x08 | isDamMethylated |
payload[0] & 0x10 | isDcmMethylated |
payload[1..] | ASCII 主序列 |
flags 位：0x01=circular，0x04=double-stranded，0x08=Dam 甲基化，0x10=Dcm 甲基化。payload[0] 为 flags 字节，payload[1..] 为 ASCII 序列。
Notes packet 0x06元信息 XML
| XML 标签 | 内部字段 |
|---|---|
AccessionNumber | accession |
Comments | description |
LastModified | date |
Organism | organism |
Features packet 0x0a注释 XML
| XML | 内部字段 |
|---|---|
Feature@type | Feature.type |
Feature@name | Feature.name |
Feature@directionality | 1 = forward, 2 = reverse |
Segment@range | Feature.start/end 或 segments[] |
Segment@color | Feature.color 或 segment color |
Q name="label" | Feature.label |
Q name="note" | Feature.note |
其他 Q | Feature.qualifiers |
Primers / StrandColors坐标转换
SnapGene 坐标是 0-based，GenePad 是 1-based inclusive。读入 +1，写出 -1，对称转换。primer location 与 StrandColors range 均如此。range 分隔符接受 .. 或 -。
| SnapGene | GenePad |
|---|---|
location="0-9" | start = 1, end = 10 |
TopStrand | forward |
BottomStrand | reverse |
Pipeline
推荐转换流程
- 解析 packet 流——从头读取 type 和 big-endian length；第一个 packet 必须是
0x09cookie。 - 构造中间模型——先构造类似
DNASequence的结构，统一使用 1-based inclusive 坐标。 - 导出 .gjson——把中间模型写成 JSON：主序列、metadata、features、baseColorRanges、primers 和 alignmentEntries。
- 导出 .gen——创建 SQLite 表，把序列写入
sequence_blocks，features / primers 写入对应表，JSON 字段序列化。
Compatibility
SnapGene .dna 兼容性原则
| 数据 | .dna 写出策略 |
|---|---|
| 主序列、拓扑、甲基化 flags | 写入标准 0x00 DNA packet |
| features、qualifiers、primers、notes、strand colors | 写入 SnapGene 兼容 XML packet |
| alignmentEntries / GenePad 专有读段 | 不写入 `.dna`；需要完整保留时使用 `.gen` 或 `.gjson` |
| 未知或无法识别的 packet | 读取时忽略，不作为 GenePad 数据恢复来源 |
为保证与 SnapGene 和第三方工具互通，`.dna` 输出只使用 SnapGene 标准 packet。无法映射到 SnapGene 标准结构的数据应保存到 GenePad 自有格式（`.gen` 或 `.gjson`）。