chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/results/frame_exports.py

@@ -0,0 +1,299 @@
+"""把明确范围内的原帧写成新ASC或复用旧封装的BLF，同时保精确逐帧索引。
+
+输入来自同次读取的新暂存，包含未参与分析和DBC未知的帧；不重新读日志/解码。
+ASC时间用整数纳秒文本；BLF沿现有writer及float秒接口，其精度和错误帧能力限制
+在清单记录，精确源时间和全部原字段保存在frames.jsonl。筛选使用分析坐标，
+写出仍保原坐标，只有显式output_offset_ns才移动输出时间。关闭后独占发布目录。
+"""
+
+from dataclasses import dataclass, replace
+from datetime import date, datetime, timedelta, timezone
+from fractions import Fraction
+import json
+from math import isfinite
+
+from ..core.models import Interval
+from ..core.validation import require_identifier
+from ..execution.history import _metadata_bytes
+from ..legacy.records import LegacyRawFrame, StoredRawFrame, frame_to_dict
+from ..legacy.export_write import LegacyCANProcessWrite
+from ..sources.raw_can import RawCANRecord
+from ..sources.text_can_decode import DecodedCANRecord
+from ..timebase.conversion import require_int64_ns, checked_add_ns, convert_time
+from .budget import _reserve_owned_ram, _release_owned_ram, _cleanup_owner
+from .export_files import ExportFiles
+
+
+@dataclass(frozen=True)
+class FrameExportSpec:
+    """选择目标格式及明确的输出时间平移；范围仍使用分析坐标，不随平移变化。"""
+
+    format: str = 'asc'
+    output_offset_ns: int = 0
+    source_time_reference: str = 'relative'
+    capture_date: str | None = None
+    timezone_offset_minutes: int | None = None
+
+    def __post_init__(self):
+        """核格式与时间。参数: 无。返回: None。异常: 不支持格式或非法偏移。
+        """
+        if self.format not in ('asc','blf') or type(self.output_offset_ns) is not int:
+            raise ValueError('原帧导出需要asc/blf和整数偏移')
+        require_int64_ns(self.output_offset_ns,'frame_export.output_offset_ns')
+        # 时间基准是声明事实，不能用偏移或大数值绕过用户要求的真实日期。
+        if self.source_time_reference not in ('relative','epoch'):
+            raise ValueError('必须明确源时间为relative或epoch，不能按数字大小猜日期')
+        if (self.capture_date is None)!=(self.timezone_offset_minutes is None):
+            raise ValueError('采集日期和时区必须一起填写')
+        if self.capture_date is not None:
+            if (type(self.capture_date) is not str or len(self.capture_date)!=10
+                    or date.fromisoformat(self.capture_date).isoformat()!=self.capture_date
+                    or type(self.timezone_offset_minutes) is not int
+                    or not -1439<=self.timezone_offset_minutes<=1439):
+                raise ValueError('需要YYYY-MM-DD实际采集日期及合法整数时区分钟')
+            if self.source_time_reference=='epoch':
+                raise ValueError('已有绝对时间不能重复叠加采集日期')
+        if self.format=='blf' and self.source_time_reference=='relative' and self.capture_date is None:
+            raise ValueError('BLF导出前必须填写实际采集日期和时区')
+
+    def date_origin_ns(self):
+        """把日内零点映射到实际当地午夜。参数: 无。返回: 精确UTC纳秒或0。异常: int64溢出。
+        """
+        if self.capture_date is None:
+            return 0
+        # 用整数日/秒换算；机器本地时区及浮点timestamp都不参与日期映射。
+        midnight=datetime.combine(date.fromisoformat(self.capture_date),datetime.min.time(),
+            timezone(timedelta(minutes=self.timezone_offset_minutes)))
+        delta=midnight-datetime(1970,1,1,tzinfo=timezone.utc)
+        value=(delta.days*86400+delta.seconds)*10**9
+        require_int64_ns(value,'frame_export.date_origin_ns')
+        return value
+
+
+@dataclass(frozen=True)
+class ExportCANFrame:
+    """统一真实/生成记录；保分析坐标、原输出坐标、完整原帧和有限原始定位。"""
+
+    sequence: int
+    time_ns: int
+    output_time_ns: int
+    frame: LegacyRawFrame
+    provenance: tuple[tuple[str,str | int | float | bool | None],...]
+    frame_origin: str = 'passthrough'
+
+    def __post_init__(self):
+        """核静态字段。参数: 无。返回: None。异常: 类型、范围、重复定位或非有限值。
+        """
+        if type(self.sequence) is not int or self.sequence<0 or type(self.frame) is not LegacyRawFrame:
+            raise TypeError('导出帧需要非负原序及LegacyRawFrame')
+        require_int64_ns(self.time_ns); require_int64_ns(self.output_time_ns)
+        if self.frame_origin not in ('passthrough','generated') or type(self.provenance) is not tuple or len(self.provenance)>32:
+            raise ValueError('导出帧种类或定位非法')
+        keys=set()
+        for pair in self.provenance:
+            if (type(pair) is not tuple or len(pair)!=2 or type(pair[0]) is not str or not pair[0]
+                    or type(pair[1]) not in (str,int,float,bool,type(None))):
+                raise TypeError('帧定位需要有限键值tuple')
+            if pair[0] in keys or type(pair[1]) is float and not isfinite(pair[1]):
+                raise ValueError('帧定位重复或非有限')
+            keys.add(pair[0])
+
+
+@dataclass(frozen=True)
+class SkippedCANFrame:
+    """保存重建未生成的网格点；不是原帧，不进入ASC/BLF，也不伪装成零载荷。"""
+
+    time_ns: int
+    reason: str
+    details: str
+
+    def __post_init__(self):
+        """核有界诊断。参数: 无。返回: None。异常: 时间、原因或文本非法。
+        """
+        require_int64_ns(self.time_ns)
+        if type(self.reason) is not str or not self.reason or type(self.details) is not str or len(self.details.encode('utf-8'))>60000:
+            raise ValueError('未生成帧需要有限原因及JSON说明文本')
+
+
+def as_export_frame(record, *, compact=False):
+    """保既有原帧及原坐标，转换有限导出外壳。参数: 真实文本/暂存/已统一帧，compact不构造追溯。返回: ExportCANFrame。异常: 类型错。
+    """
+    if type(record) is ExportCANFrame:
+        return record
+    if type(record) is StoredRawFrame:
+        # 旧BLF原float秒与分析offset分开，不把映射后的时间回写原报文。
+        converted=convert_time(record.frame.timestamp,'s')
+        return ExportCANFrame(record.sequence,record.time_ns,converted.time_ns,record.frame,
+            () if compact else (('profile','sclicer-functions-v1'),('yield_sequence',record.sequence),
+             ('timestamp',record.frame.timestamp),('time_quantized',converted.quantized)))
+    if type(record) in (RawCANRecord,DecodedCANRecord):
+        raw=record.raw if type(record) is DecodedCANRecord else record
+        provenance=() if compact else (('path',str(raw.path)),('line_number',raw.line_number),('parser_version',raw.parser_version),
+            ('record_sequence',raw.sequence),('raw_time',raw.raw_time),('time_quantized',raw.time_quantized))
+        if not compact and type(record) is DecodedCANRecord:
+            provenance+=(('input_index',record.input_index),('decode_status',record.status))
+        # 分析offset只决定筛选位置；导出日期应叠加原始日内时间，不能叠加归零后的分析时间。
+        source_ns=raw.time_ns if raw.source_time_ns is None else raw.source_time_ns
+        return ExportCANFrame(record.sequence,raw.time_ns,source_ns,raw.frame,provenance)
+    raise TypeError('帧导出需要同次原始/解码暂存记录')
+
+
+def _asc_line(record,output_ns):
+    """写标准ASC数据行及无法表达的原字段名单。参数: record、非负精确输出ns。返回: (bytes,losses)。异常: 格式不可表达。
+    """
+    frame=record.frame
+    if frame.is_rx is None:
+        raise ValueError('原始报文导出需要收发方向is_rx，不能把未知方向写为Tx或Rx')
+    if output_ns<0 or type(frame.channel) is not int or not 0<=frame.channel<65536:
+        raise ValueError('ASC需要非负时间和明确0基整数通道')
+    seconds,nanos=divmod(output_ns,10**9)
+    prefix=f'{seconds}.{nanos:09d}'
+    channel=str(frame.channel+1); direction='Rx' if frame.is_rx else 'Tx'
+    identifier=format(frame.arbitration_id,'x')+('x' if frame.is_extended_id else '')
+    if not frame.is_extended_id and frame.arbitration_id>0x7ff:
+        raise ValueError('ASC标准帧ID超出11位')
+    if frame.is_error_frame:
+        # 标准错误行不能保存数据帧附加字段；完整原值保在索引，清单明确格式损失。
+        expected={'arbitration_id':0,'is_extended_id':False,'dlc':0,'data':b'',
+                  'bitrate_switch':False,'error_state_indicator':False,'is_remote_frame':False}
+        if not frame.is_fd:
+            expected['is_rx']=True
+        losses=tuple(k for k,v in expected.items() if getattr(frame,k)!=v)
+        body=f'CANFD {channel} {direction} ErrorFrame' if frame.is_fd else f'{channel} ErrorFrame'
+    else:
+        losses=()
+        if frame.is_remote_frame:
+            if frame.is_fd or frame.data or not 0<=frame.dlc<=8:
+                raise ValueError('ASC远程帧需要经典CAN、空数据和0至8 DLC')
+            body=f'{channel} {identifier} {direction} r {frame.dlc:x}'
+        elif frame.is_fd:
+            lengths=(0,1,2,3,4,5,6,7,8,12,16,20,24,32,48,64)
+            if frame.dlc!=len(frame.data) or frame.dlc not in lengths:
+                raise ValueError('ASC FD长度或DLC不一致')
+            body=f'CANFD {channel} {direction} {identifier} {int(frame.bitrate_switch)} {int(frame.error_state_indicator)} {lengths.index(frame.dlc):x} {frame.dlc} '+frame.data.hex(' ')
+        else:
+            if frame.dlc!=len(frame.data) or frame.dlc>8:
+                raise ValueError('ASC经典帧长度不一致')
+            body=f'{channel} {identifier} {direction} d {frame.dlc:x} '+frame.data.hex(' ')
+        if not frame.is_fd:
+            losses=tuple(k for k in ('bitrate_switch','error_state_indicator') if getattr(frame,k))
+    return (prefix+' '+body.rstrip()+'\n').encode('ascii'),losses
+
+
+def export_can_frames(records,spec,interval,destination,budget,*,source,device_label,check_cancel=None,compact=False,integrity=True,file_consumer=None):
+    """逐条筛选并写出原始范围，完整消费新暂存后发布。
+
+    参数: records同次可关闭原帧流；spec格式/偏移；interval半开分析范围；destination新目录；
+        budget共享账本；source来源名；device_label设备；check_cancel取消回调；
+        compact关闭逐帧副本/三时间/误差计算，仅保目标帧和必要清单。
+    返回: 已发布目录Path，含frames.asc/blf和manifest.json；旧完整模式另有frames.jsonl。
+    异常: 格式/时间/原历史/I/O/预算/取消错；持续清理失败保export_cleanup_owner。
+    """
+    if type(compact) is not bool:
+        raise TypeError('compact必须为bool')
+    if type(spec) is not FrameExportSpec or type(interval) is not Interval:
+        raise TypeError('帧导出需要FrameExportSpec和Interval')
+    require_identifier(source,'frame_export.source')
+    if device_label not in ('home','work') or check_cancel is not None and not callable(check_cancel):
+        raise ValueError('帧导出需要实际设备及可选取消回调')
+    date_origin=spec.date_origin_ns()
+    output_offset=checked_add_ns(date_origin,spec.output_offset_ns)
+    if file_consumer is not None and not callable(file_consumer):
+        raise TypeError('file_consumer须为回调')
+    owner=ExportFiles(destination,budget,integrity=integrity)
+    try:
+        if not compact:
+            owner.open_file('frames.jsonl')
+        if spec.format=='asc':
+            owner.select_file('frames.asc')
+            owner.append(b'base hex timestamps absolute\nno internal events logged\n')
+        else:
+            try:
+                owner.worker=LegacyCANProcessWrite(budget,owner.temporary/'frames.blf')
+            except BaseException as error:
+                owner.worker=getattr(error,'can_process_write_cleanup_owner',None)
+                raise
+        owner.reader=iter(records)
+        reconstruction=getattr(owner.reader,'export_metadata',None)
+        if reconstruction is not None:
+            _reserve_owned_ram(owner,_metadata_bytes(reconstruction)*16,'_fixed_cost')
+        count=generated=limited=skipped=0
+        max_float_error=0
+        last=None
+        for raw in owner.reader:
+            if check_cancel is not None:
+                check_cancel()
+            _reserve_owned_ram(owner,1048576+(_metadata_bytes(raw.provenance)*16
+                               if type(raw) is ExportCANFrame else len(raw.details.encode('utf-8'))*16
+                               if type(raw) is SkippedCANFrame else 0),'_row_cost')
+            try:
+                if type(raw) is SkippedCANFrame:
+                    if last is not None and raw.time_ns<last:
+                        raise ValueError('未生成帧记录时间回退')
+                    last=raw.time_ns
+                    if interval.start_ns<=raw.time_ns<interval.end_ns:
+                        if not compact:
+                            owner.select_file('skipped_frames.jsonl')
+                            owner.append((json.dumps({'time_ns':raw.time_ns,'reason':raw.reason,'details':raw.details},
+                                ensure_ascii=False,separators=(',',':'))+'\n').encode('utf-8'))
+                        skipped+=1
+                    continue
+                record=as_export_frame(raw,compact=True) if compact else as_export_frame(raw)
+                if last is not None and record.time_ns<last:
+                    raise ValueError('导出帧时间回退，不能重排原记录')
+                last=record.time_ns
+                if not interval.start_ns<=record.time_ns<interval.end_ns:
+                    continue
+                if record.frame.is_rx is None:
+                    raise ValueError('原始报文导出需要收发方向is_rx')
+                output_ns=checked_add_ns(record.output_time_ns,output_offset)
+                if spec.format=='asc':
+                    payload,losses=_asc_line(record,output_ns)
+                    owner.select_file('frames.asc'); owner.append(payload)
+                else:
+                    # 不调用旧库的隐式“相对时间头归零”分支；缺日期先要求显式映射。
+                    if output_ns<631152000*10**9:
+                        raise ValueError('现有BLF写库不支持1990年以前的日期，不能改写为固定参考日期')
+                    if type(record.frame.channel) is not int or not 0<=record.frame.channel<65535:
+                        raise ValueError('BLF需要0至65534的明确整数通道，避免写库隐式改通道')
+                    # 库接口仅接受float秒；记录转换误差，同时以整数索引保留精确真值。
+                    timestamp=output_ns/10**9
+                    if not compact:
+                        delta=abs(Fraction(timestamp)*10**9-output_ns)
+                        max_float_error=max(max_float_error,(delta.numerator+delta.denominator-1)//delta.denominator)
+                    owner.worker.write(replace(record.frame,timestamp=timestamp))
+                    losses=('error_frame_flags_or_payload',) if record.frame.is_error_frame else ()
+                if not compact:
+                    owner.select_file('frames.jsonl')
+                    packet={'index':count,'source':source,'sequence':record.sequence,'analysis_time_ns':record.time_ns,
+                        'source_time_ns':record.output_time_ns,'output_time_ns':output_ns,'frame_origin':record.frame_origin,
+                        'provenance':dict(record.provenance),'frame':frame_to_dict(record.frame),'format_limits':losses}
+                    owner.append((json.dumps(packet,ensure_ascii=False,allow_nan=False,separators=(',',':'))+'\n').encode('utf-8'))
+                count+=1; generated+=record.frame_origin=='generated'; limited+=bool(losses)
+            finally:
+                _release_owned_ram(owner,owner._row_cost,'_row_cost')
+        owner.close_reader()
+        # 旧写进程真正结束后才能回读摘要；文件没关、摘要失败均不发布正式目录。
+        if owner.worker is not None:
+            owner.worker.finish()
+            owner.worker=None
+            owner.register_external('frames.blf')
+        metadata={'frame_origin':'can_frames','device_label':device_label,'source':source,'format':spec.format,
+            'range_ns':(interval.start_ns,interval.end_ns),'output_offset_ns':spec.output_offset_ns,
+            'source_time_reference':spec.source_time_reference,'capture_date':spec.capture_date,
+            'timezone_offset_minutes':spec.timezone_offset_minutes,'date_origin_ns':date_origin,
+            'frames':count,'generated':generated,'passthrough':count-generated,'format_limited_frames':limited,
+            'skipped_grid_points':skipped,
+            'reconstruction':reconstruction,
+            'time_precision':'integer_ns_text' if spec.format=='asc' else 'legacy_float_seconds',
+            }
+        if compact:
+            metadata['row_format']='compact-v2'
+        else:
+            metadata.update(max_float_conversion_error_ns=max_float_error,exact_source_index='frames.jsonl')
+        output=owner.finish(metadata)
+        if file_consumer is not None: file_consumer(tuple(owner.files))
+        return output
+    except BaseException as error:
+        _cleanup_owner(owner,error,'export_cleanup_owner','原始报文导出')
+        raise

chronaxis/results/frame_patch.py

@@ -0,0 +1,186 @@
+"""用已有DBC位域工具更新明确的连续信号，其他位沿用同一基础帧。
+
+调用者传入本次已加载的cantools Message及本次已解码的物理值，不再次读取DBC
+或解码原帧。整数按nearest_even-v1量化，浮点沿DBC编码后核实际表示误差。
+码值或物理值越界立即拒绝。只更新选中位的掩码，计数、校验及未知位保持；
+这些生成帧不承诺校验码有效或可用于车辆回放。
+"""
+
+from dataclasses import dataclass, replace
+from fractions import Fraction
+from math import isfinite
+
+from .budget import _reserve_owned_ram, _release_owned_ram, _cleanup_owner
+from ..legacy.records import normalize_frame_id
+
+
+@dataclass(frozen=True)
+class FrameRebuildRule:
+    """明确报文身份、连续字段及禁止插值的字段；声明不能从名字猜业务含义。"""
+
+    channel: int
+    frame_id: int
+    continuous: tuple[str,...]
+    is_extended: bool | None = None  # 省略时按实际帧与DBC确定，不等同标准帧。
+    is_fd: bool | None = None  # 省略时保留输入帧的实际CAN/FD类型。
+    protected: tuple[str,...] = ()
+    same_time_policy: str = 'error'
+
+    def __post_init__(self):
+        """核身份和字段分类。参数: 无。返回: None。异常: 非法/重复/保护字段冲突。
+        """
+        # ID只在规则建立时归一化，避免每个输出帧重新解释进制。
+        object.__setattr__(self,'frame_id',normalize_frame_id(self.frame_id))
+        if (type(self.channel) is not int or self.channel<0
+                or self.is_extended is False and self.frame_id>0x7ff
+                or self.is_extended is not None and type(self.is_extended) is not bool
+                or self.is_fd is not None and type(self.is_fd) is not bool
+                or self.same_time_policy not in ('error','last_by_sequence')):
+            raise ValueError('报文重建身份或同刻策略非法')
+        for names in (self.continuous,self.protected):
+            if type(names) is not tuple or len(names)>4096 or any(type(n) is not str or not n for n in names) or len(set(names))!=len(names):
+                raise ValueError('报文重建字段需要唯一非空名称tuple')
+        if not self.continuous or set(self.continuous)&set(self.protected):
+            raise ValueError('必须选择连续量，且不能插值保护的计数或校验字段')
+
+    def matches(self,frame):
+        """按实际帧身份匹配。参数: frame原帧。返回: bool。异常: 原模型访问错。
+        """
+        return (frame.channel==self.channel and frame.arbitration_id==self.frame_id
+            and (self.is_extended is None or frame.is_extended_id==self.is_extended)
+            and (self.is_fd is None or frame.is_fd==self.is_fd))
+
+
+class DBCFramePatch:
+    """借用一条已加载DBC定义，拥有选中位格式与预算；只缓存当前复用布局。"""
+
+    def __init__(self,rule,message,budget):
+        """核DBC身份与连续字段并预约格式空间。参数: rule/message/budget。返回: patcher。异常: 不匹配或预算错。
+        """
+        if type(rule) is not FrameRebuildRule:
+            raise TypeError('需要FrameRebuildRule')
+        self.rule=rule; self.message=message; self._budget=budget
+        self._held_cost=self._fixed_cost=0; self._closed=False
+        self.signals={}; self.formats=None; self.active=(); self.mask=0
+        self._identity=None
+        try:
+            _reserve_owned_ram(self,262144+len(message.signals)*16384,'_fixed_cost')
+            if (message.frame_id!=rule.frame_id
+                    or rule.is_extended is not None and message.is_extended_frame!=rule.is_extended
+                    or rule.is_fd is True and not message.is_fd
+                    or not 0<message.length<=64 or message.is_container):
+                raise ValueError('重建规则与DBC报文身份/载荷不符或为容器报文')
+            self.signals={signal.name:signal for signal in message.signals}
+            for name in (*rule.continuous,*rule.protected):
+                if name not in self.signals:
+                    raise ValueError('DBC缺少重建声明字段: '+name)
+            for name in rule.continuous:
+                signal=self.signals[name]
+                if signal.is_multiplexer or signal.choices or not signal.scale or signal.length==1:
+                    raise ValueError('复用选择器、枚举/布尔或零倍率不能当连续量: '+name)
+        except BaseException as error:
+            _cleanup_owner(self,error,'frame_patch_cleanup_owner','DBC位域重建构造')
+            raise
+
+    def accept_frame(self,frame):
+        """检查实际基础帧与选定DBC，并识别自动规则后续出现的帧型冲突。
+
+        参数: frame为同次输入原帧。返回: None。异常: ValueError为类型不匹配或歧义。
+        副作用: 只记录首次匹配的两个类型标志，后续同型帧不扩大状态。
+        """
+        if (not self.rule.matches(frame) or frame.is_extended_id!=self.message.is_extended_frame
+                or frame.is_fd and not self.message.is_fd):
+            raise ValueError('重建实际帧与已选DBC类型不符')
+        identity=(frame.is_extended_id,frame.is_fd)
+        if self._identity is not None and self._identity!=identity:
+            flag='is_extended' if self._identity[0]!=identity[0] else 'is_fd'
+            raise ValueError('重建规则匹配多种实际帧类型，请补充'+flag)
+        self._identity=identity
+
+    def selected(self,layout):
+        """只取当前复用分支适用的连续字段。参数: layout原生选择器码值tuple。返回: 名称tuple。异常: 布局非法。
+        """
+        selectors=dict(layout)
+        if len(selectors)!=len(layout) or any(name not in self.signals or not self.signals[name].is_multiplexer
+                or type(value) is not int for name,value in layout):
+            raise ValueError('报文复用布局不合法')
+        selected=[]
+        for name in self.rule.continuous:
+            signal=self.signals[name]; visited=set(); applicable=True
+            # 沿真实父选择器判断，避免将另一分支同位置的位当作本连续量。
+            while signal.multiplexer_signal is not None:
+                parent=signal.multiplexer_signal
+                if parent in visited or parent not in self.signals:
+                    raise ValueError('DBC复用父链非法')
+                visited.add(parent)
+                if parent not in selectors or selectors[parent] not in signal.multiplexer_ids:
+                    applicable=False; break
+                signal=self.signals[parent]
+            if applicable:
+                selected.append(name)
+        return tuple(selected)
+
+    def patch(self,base,values,layout,*,exact_values=None,trace=True):
+        """仅按允许掩码更新载荷并记录量化误差。
+
+        参数: base同一基础LegacyRawFrame；values所需物理估计dict；layout实际复用布局；
+            exact_values可选的有理数编码目标，用于避免中间float改变半码决策。
+        返回: (新帧, 每字段目标/码值/实际值/误差tuple)。异常: 缺值、范围/格式/编码错误。
+        """
+        if self._closed or not self.rule.matches(base) or base.dlc!=self.message.length or len(base.data)!=self.message.length:
+            raise ValueError('重建基础帧已关闭、身份或长度不符')
+        self.accept_frame(base)
+        selected=self.selected(layout)
+        if not selected or set(values)!=set(selected):
+            raise ValueError('当前复用布局缺少必须的连续值')
+        if exact_values is not None and (set(exact_values)!=set(selected) or any(type(v) is not Fraction for v in exact_values.values())):
+            raise ValueError('精确量化目标需要同组Fraction字段')
+        from cantools.database.utils import create_encode_decode_formats,encode_data,decode_data
+        if selected!=self.active:
+            # 编解码格式来自现有库；仅所选信号的非padding位允许改变。
+            self.formats=create_encode_decode_formats([self.signals[n] for n in selected],self.message.length)
+            self.mask=((1<<(self.message.length*8))-1)^self.formats.padding_mask
+            self.active=selected
+        raw={}
+        for name in selected:
+            signal=self.signals[name]; value=values[name]
+            if type(value) not in (int,float) or not isfinite(value):
+                raise ValueError('重建物理值必须有限: '+name)
+            physical=Fraction(str(value)) if exact_values is None else exact_values[name]
+            scale=Fraction(str(signal.scale)); offset=Fraction(str(signal.offset))
+            if ((signal.minimum is not None and physical<Fraction(str(signal.minimum)))
+                    or (signal.maximum is not None and physical>Fraction(str(signal.maximum)))):
+                raise ValueError('重建目标物理值越界: '+name)
+            code=(physical-offset)/scale
+            if signal.is_float:
+                raw[name]=float(code)
+            else:
+                # Fraction的round精确实现最近整数/恰半取偶，负倍率和负值同样适用。
+                integer=round(code)
+                low=-(1<<(signal.length-1)) if signal.is_signed else 0
+                high=(1<<(signal.length-int(signal.is_signed)))-1
+                if not low<=integer<=high:
+                    raise ValueError('重建码值超出位宽: '+name)
+                raw[name]=integer
+        fields=[self.signals[n] for n in selected]
+        encoded=encode_data(raw,fields,self.formats,scaling=False)
+        payload=((int.from_bytes(base.data,'big')&~self.mask)|(encoded&self.mask)).to_bytes(self.message.length,'big')
+        decoded=decode_data(payload,self.message.length,fields,self.formats,False,True,False,False)
+        facts=[]
+        for name in selected:
+            signal=self.signals[name]; actual=decoded[name]
+            if (not isfinite(actual) or signal.minimum is not None and actual<signal.minimum
+                    or signal.maximum is not None and actual>signal.maximum):
+                raise ValueError('重建量化后物理值越界: '+name)
+            if trace:
+                target=Fraction(str(values[name])) if exact_values is None else exact_values[name]
+                facts.append((name,float(target),raw[name],actual,float(Fraction(str(actual))-target)))
+        return replace(base,data=payload),tuple(facts)
+
+    def close(self):
+        """释放本格式缓存，不关闭借用DBC。参数: 无。返回: None。异常: 费用释放错可重试。
+        """
+        if self._closed:
+            return
+        self.signals.clear(); self.formats=None; self.message=None; self.active=()
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost'); self._closed=True