ecode-cutting 0.2.3__py3-none-any.whl

ecode_cutting/engine.py

@@ -0,0 +1,558 @@
+"""独立任务引擎：管理输入、调用求解器并查询结果，不依赖 Web 框架。"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import asdict, fields, replace
+from pathlib import Path
+from threading import Lock
+from typing import Callable
+
+from ._common import Runtime, integer, normalize_options, number, validate
+from .models import (
+    Cut, Layout, LayoutGroup, Material, Options, Part, Placement, Progress,
+    Remnant, Result, Stock, StockComponent, ValidationError,
+)
+
+
+def _pascal(name: str) -> str:
+    return "".join(word.capitalize() for word in name.split("_"))
+
+
+_OPTION_NAMES = {_pascal(f.name): f.name for f in fields(Options)}
+
+
+def _layout_key(layout: Layout) -> tuple:
+    """不以零件编号分组；逐件溯源仍完整保存在每一张布局中。"""
+    return (layout.input_index, layout.width, layout.height,
+            tuple(sorted((p.width, p.height, p.x, p.y, p.rotated, p.flipped,
+                          p.angle_start, p.angle_end, p.material) for p in layout.parts)),
+            tuple((c.x1, c.y1, c.x2, c.y2, c.level) for c in layout.cuts))
+
+
+def group_layouts(result: Result, options: Options) -> Result:
+    groups: dict[tuple, list[Layout]] = defaultdict(list)
+    for layout in result.layouts:
+        groups[_layout_key(layout)].append(layout)
+    layouts: list[Layout] = []
+    summaries: list[LayoutGroup] = []
+    for group in groups.values():
+        limit = (options.max_layout_size if options.use_layout_minimization else 0) or len(group)
+        for start in range(0, len(group), limit):
+            chunk = group[start:start + limit]
+            summaries.append(LayoutGroup(len(layouts), len(chunk)))
+            layouts.extend(chunk)
+    return replace(result, layouts=tuple(layouts), layout_groups=tuple(summaries))
+
+
+class CutEngine:
+    """一个实例表示一个切割任务；Web 的不同请求应分别创建实例。
+
+    Python 接口返回数据模型，非法参数抛 ValidationError。旧 PascalCase 名称
+    作为迁移别名保留，但不仿造 .NET 的 out 参数和授权注册接口。
+    """
+
+    version = "0.2.3"
+
+    def __init__(self, options: Options | None = None, **settings):
+        self.options = normalize_options(options) if options is not None else Options()
+        self._parts: list[Part] = []
+        self._stocks: list[Stock] = []
+        self._materials: list[Material] = []
+        self._result: Result | None = None
+        self._result_options: Options | None = None
+        self._locations_cache: list[tuple[int, Placement] | None] | None = None
+        self._lock = Lock()
+        self._running = False
+        for name, value in settings.items():
+            field_name = _OPTION_NAMES.get(name, name)
+            if field_name not in Options.__dataclass_fields__:
+                raise TypeError(f"未知计算参数：{name}")
+            setattr(self.options, field_name, value)
+        self.options = normalize_options(self.options)
+
+    def __getattr__(self, name):
+        if name in _OPTION_NAMES:
+            return getattr(self.options, _OPTION_NAMES[name])
+        raise AttributeError(name)
+
+    def __setattr__(self, name, value):
+        if name in _OPTION_NAMES and "options" in self.__dict__:
+            setattr(self.options, _OPTION_NAMES[name], value)
+        else:
+            object.__setattr__(self, name, value)
+
+    @property
+    def parts(self) -> tuple[Part, ...]:
+        return tuple(self._parts)
+
+    @property
+    def stocks(self) -> tuple[Stock, ...]:
+        return tuple(self._stocks)
+
+    @property
+    def materials(self) -> tuple[Material, ...]:
+        return tuple(self._materials)
+
+    @property
+    def result(self) -> Result:
+        if self._result is None:
+            raise RuntimeError("请先执行 execute() 或 execute_linear()")
+        return self._result
+
+    def _modify(self, action):
+        with self._lock:
+            if self._running:
+                raise RuntimeError("同一引擎正在计算，不能同时修改输入")
+            value = action()
+            self._result = None
+            self._result_options = None
+            self._locations_cache = None
+            return value
+
+    def clear(self, *, reset_options: bool = False) -> None:
+        """清空输入和结果；原生接口默认保留选项，文档兼容入口另行重置。"""
+        def reset():
+            self._parts.clear()
+            self._stocks.clear()
+            self._materials.clear()
+            if reset_options:
+                self.options = Options()
+        self._modify(reset)
+
+    def add_material(self, id: str = "", description: str = "", thickness: float = 0.0) -> int:
+        if not isinstance(id, str) or not isinstance(description, str):
+            raise ValidationError("材料编号和描述必须是字符串")
+        thickness = number(thickness, "thickness")
+        def append():
+            self._materials.append(Material(id, description, thickness))
+            return len(self._materials) - 1
+        return self._modify(append)
+
+    def get_material(self, material: int) -> Material:
+        return self._at(self._materials, material)
+
+    def add_part(self, width: float, height: float, count: int = 1,
+                 rotatable: bool = True, id: str = "", material: int = -1) -> bool:
+        part = Part(number(width, "width", positive=True), number(height, "height", positive=True),
+                    count, rotatable, id, material)
+        validate((), (part,), Options(max_decimal_point=6), linear=False)
+        self._modify(lambda: self._parts.append(part))
+        return True
+
+    def add_stock(self, width: float, height: float, count: int = 1,
+                  id: str = "", waste: bool = False, material: int = -1) -> bool:
+        stock = Stock(number(width, "width", positive=True), number(height, "height", positive=True),
+                      count, id, waste, material)
+        validate((stock,), (), Options(max_decimal_point=6), linear=False)
+        self._modify(lambda: self._stocks.append(stock))
+        return True
+
+    def add_linear_part(self, length: float, count: int = 1, *, id: str = "",
+                        material: int = -1, angle_start: float = 0.0,
+                        angle_end: float = 0.0) -> bool:
+        part = Part(number(length, "length", positive=True), 1.0, count, False, id, material,
+                    number(angle_start, "angle_start"), number(angle_end, "angle_end"))
+        # 输入阶段允许稍后设置截面和更细的计算精度，最终执行时统一核验。
+        validate((), (part,), Options(cross_section=1, max_decimal_point=6), linear=True)
+        self._modify(lambda: self._parts.append(part))
+        return True
+
+    def add_linear_stock(self, length: float, count: int = 1, *, id: str = "",
+                         waste: bool = False, material: int = -1) -> bool:
+        stock = Stock(number(length, "length", positive=True), 1.0, count, id, waste, material)
+        validate((stock,), (), Options(max_decimal_point=6), linear=True)
+        self._modify(lambda: self._stocks.append(stock))
+        return True
+
+    def set_vertical_cut_direction(self, roll_mode: bool = False) -> None:
+        self._set_direction("vertical", roll_mode)
+
+    def set_horizontal_cut_direction(self, roll_mode: bool = False) -> None:
+        self._set_direction("horizontal", roll_mode)
+
+    def set_auto_cut_direction(self) -> None:
+        self._set_direction("auto", False)
+
+    def _set_direction(self, direction: str, roll_mode: bool):
+        if type(roll_mode) is not bool:
+            raise ValidationError("roll_mode 必须是布尔值")
+        def change():
+            self.options.cut_direction = direction
+            self.options.roll_mode = roll_mode
+        self._modify(change)
+
+    def execute(self, callback: Callable[[Progress], bool] | None = None) -> Result:
+        return self._execute(False, callback)
+
+    def execute_linear(self, callback: Callable[[Progress], bool] | None = None) -> Result:
+        return self._execute(True, callback)
+
+    def execute_linear_fast(self, callback: Callable[[Progress], bool] | None = None) -> Result:
+        """新增快速入口；复杂工艺自动使用完整求解器，原 execute_linear 行为不变。"""
+        from ._linear_fast import solve_linear_fast
+        return self._execute(True, callback, solver=solve_linear_fast)
+
+    def optimize_linear_plans(self, *, max_plans: int = 3, time_limit: float = 5.0,
+                              max_searches: int = 12,
+                              callback: Callable[[Progress], bool] | None = None):
+        """在共享预算内返回多种一维方案，不覆盖本引擎已有计算结果。"""
+        return self._optimize_plans(True, max_plans, time_limit, max_searches, callback)
+
+    def optimize_plans(self, *, max_plans: int = 3, time_limit: float = 5.0,
+                       max_searches: int = 12,
+                       callback: Callable[[Progress], bool] | None = None):
+        """在共享预算内返回多种二维方案；物理工艺约束在各方案中保持不变。"""
+        return self._optimize_plans(False, max_plans, time_limit, max_searches, callback)
+
+    def _optimize_plans(self, linear, max_plans, time_limit, max_searches, callback):
+        from .portfolio import search_portfolio
+        with self._lock:
+            if self._running:
+                raise RuntimeError("同一引擎不能同时执行两个计算，请为每个请求新建实例")
+            options, stocks, parts = normalize_options(self.options), self.stocks, self.parts
+            self._running = True
+        try:
+            return search_portfolio(stocks, parts, options, linear=linear, max_plans=max_plans,
+                                    time_limit=time_limit, max_searches=max_searches, callback=callback)
+        finally:
+            with self._lock:
+                self._running = False
+
+    def _execute(self, linear: bool, callback, *, solver=None) -> Result:
+        with self._lock:
+            if self._running:
+                raise RuntimeError("同一引擎不能同时执行两个计算，请为每个请求新建实例")
+            # 快照可以因公开配置被赋错类型而失败；在置忙之前完成，保证任务仍可清空重试。
+            options = normalize_options(self.options)
+            stocks, parts = self.stocks, self.parts
+            self._running = True
+            self._result = None
+            self._locations_cache = None
+        try:
+            validate(stocks, parts, options, linear=linear)
+            if callback is not None and not callable(callback):
+                raise ValidationError("callback 必须可调用")
+            runtime = Runtime(options, sum(p.count for p in parts), callback)
+            if solver is not None:
+                result = solver(stocks, parts, options, runtime)
+            elif linear:
+                from .linear import solve_linear
+                result = solve_linear(stocks, parts, options, runtime)
+            else:
+                from .rectangular import solve_rectangular
+                result = solve_rectangular(stocks, parts, options, runtime)
+            self._result = group_layouts(result, options)
+            self._result_options = options
+            return self._result
+        finally:
+            with self._lock:
+                self._running = False
+
+    @staticmethod
+    def _at(items, index):
+        if type(index) is not int or not 0 <= index < len(items):
+            raise IndexError(f"索引超出范围：{index}")
+        return items[index]
+
+    def _part_locations(self) -> list[tuple[int, Placement] | None]:
+        if self._locations_cache is not None:
+            return self._locations_cache
+        locations = {(p.input_index, p.instance_index): (s, p)
+                     for s, layout in enumerate(self.result.layouts) for p in layout.parts}
+        self._locations_cache = [locations.get((i, n)) for i, part in enumerate(self._parts) for n in range(part.count)]
+        return self._locations_cache
+
+    def get_result_part(self, part: int) -> tuple[int, Placement] | None:
+        """按输入展开序号查询；未放置返回 None，避免重排后丢失订单映射。"""
+        return self._at(self._part_locations(), part)
+
+    get_result_linear_part = get_result_part
+
+    def get_stock_info(self, stock: int) -> Layout:
+        return self._at(self.result.layouts, stock)
+
+    get_linear_stock_info = get_stock_info
+
+    def get_part_count_on_stock(self, stock: int) -> int:
+        return len(self.get_stock_info(stock).parts)
+
+    def get_part_index_on_stock(self, stock: int, part: int) -> int:
+        placement = self._at(self.get_stock_info(stock).parts, part)
+        return sum(p.count for p in self._parts[:placement.input_index]) + placement.instance_index
+
+    def get_part_material(self, part: int) -> int:
+        self._at(self._part_locations(), part)
+        for p in self._parts:
+            if part < p.count:
+                return p.material
+            part -= p.count
+        raise IndexError(part)
+
+    def get_stock_material(self, stock: int) -> int:
+        return self.get_stock_info(stock).material
+
+    def _remnants(self) -> list[tuple[int, Remnant]]:
+        return [(s, r) for s, layout in enumerate(self.result.layouts) for r in layout.all_remnants]
+
+    def get_remaining_part(self, part: int) -> tuple[int, Remnant]:
+        return self._at(self._remnants(), part)
+
+    get_remaining_linear_part = get_remaining_part
+
+    def get_remaining_part_material(self, part: int) -> int:
+        return self.get_remaining_part(part)[1].material
+
+    def get_remaining_part_count_on_stock(self, stock: int) -> int:
+        return len(self.get_stock_info(stock).all_remnants)
+
+    def get_remaining_part_index_on_stock(self, stock: int, part: int) -> int:
+        self._at(self.get_stock_info(stock).all_remnants, part)
+        return sum(len(s.all_remnants) for s in self.result.layouts[:stock]) + part
+
+    def _cuts(self) -> list[tuple[int, Cut]]:
+        return [(s, c) for s, layout in enumerate(self.result.layouts) for c in layout.cuts]
+
+    def get_cuts_count(self) -> int:
+        return sum(len(s.cuts) for s in self.result.layouts)
+
+    get_linear_cuts_count = get_cuts_count
+
+    def get_cut(self, cut: int) -> tuple[int, Cut]:
+        return self._at(self._cuts(), cut)
+
+    get_linear_cut = get_cut
+
+    def get_stock_cut_count(self, stock: int) -> int:
+        return len(self.get_stock_info(stock).cuts)
+
+    def get_stock_cut(self, stock: int, cut: int) -> Cut:
+        return self._at(self.get_stock_info(stock).cuts, cut)
+
+    get_linear_stock_cut = get_stock_cut
+
+    def get_stock_trim_cut_count(self, stock: int) -> int:
+        return len(self.get_stock_info(stock).trim_cuts)
+
+    def get_stock_trim_cut(self, stock: int, cut: int) -> Cut:
+        return self._at(self.get_stock_info(stock).trim_cuts, cut)
+
+    def _part_cuts(self, part: int) -> tuple[int, list[Cut]]:
+        located = self.get_result_part(part)
+        if located is None:
+            return -1, []
+        stock, placement = located
+        layout = self.result.layouts[stock]
+        index = layout.parts.index(placement)
+        cuts = [c for c in layout.cuts if index in c.part_indices]
+        return stock, cuts
+
+    def get_part_cuts_count(self, part: int) -> int:
+        return len(self._part_cuts(part)[1])
+
+    def get_part_cut(self, part: int, cut: int) -> tuple[int, Cut]:
+        stock, cuts = self._part_cuts(part)
+        return stock, self._at(cuts, cut)
+
+    def get_linear_combine_stock_count(self, stock: int) -> int:
+        components = self.get_stock_info(stock).components
+        return len(components) if len(components) > 1 else 0
+
+    def get_linear_combine_stock_components(self, stock: int) -> tuple[StockComponent, ...]:
+        layout = self.get_stock_info(stock)
+        return layout.components or (StockComponent(layout.input_index, layout.instance_index,
+            layout.width, layout.id, layout.waste, layout.material),)
+
+    def get_linear_combine_stock_info(self, stock: int, index: int) -> StockComponent:
+        return self._at(self.get_linear_combine_stock_components(stock), index)
+
+    def get_layout_info(self, layout: int) -> LayoutGroup:
+        return self._at(self.result.layout_groups, layout)
+
+    def get_layout_fill_ratio(self, layout: int) -> float:
+        group = self.get_layout_info(layout)
+        stock = self.result.layouts[group.first_layout_index]
+        if self._result_options is not None and self._result_options.cross_section > 0:
+            return (stock.width - sum(r.width for r in stock.remnants)) / stock.width
+        return stock.fill_ratio
+
+    @property
+    def part_count(self) -> int:
+        return sum(p.count for p in self._parts)
+
+    @property
+    def remaining_part_count(self) -> int:
+        return len(self._remnants())
+
+    @property
+    def stock_count(self) -> int:
+        return len(self.result.layouts)
+
+    @property
+    def used_stock_count(self) -> int:
+        return self.result.used_stock_count
+
+    linear_stock_count = stock_count
+    used_linear_stock_count = used_stock_count
+
+    @property
+    def layout_count(self) -> int:
+        return len(self.result.layout_groups)
+
+    @property
+    def elapsed_time(self) -> float:
+        return self.result.elapsed
+
+    @property
+    def placed_part_count(self) -> int:
+        return self.result.placed_part_count
+
+    @property
+    def is_linear_run(self) -> bool:
+        return self._result is not None and self._result.linear
+
+    @property
+    def max_part_sizes(self) -> None:
+        """零件规格类数量不受旧产品授权上限限制；None 表示无限制。"""
+        return None
+
+    @property
+    def max_size_sizes(self) -> None:
+        """原料规格类数量不受旧产品授权上限限制；None 表示无限制。"""
+        return None
+
+    def export_csv(self, target) -> None:
+        from .exporters import export_csv
+        export_csv(self.result, target)
+
+    def export_dxf(self, target, include_part_ids: bool = True) -> None:
+        from .exporters import export_dxf
+        export_dxf(self.result, target, include_part_ids=include_part_ids)
+
+    def export_cuts_dxf(self, target, include_cut_number: bool = True,
+                        include_stock_panel: bool = True) -> None:
+        from .exporters import export_dxf
+        export_dxf(self.result, target, cuts_only=True, include_cut_number=include_cut_number,
+                   include_stock_panel=include_stock_panel)
+
+    def export_ptx(self, target, job_name="", customer="", material="", material_thickness=0,
+                   units=0, unit_scale=1, require_all_trim_cuts=False) -> None:
+        from .exporters import export_ptx
+        export_ptx(self.result, target, job_name=job_name, customer=customer, material=material,
+                   material_thickness=material_thickness, units=units, unit_scale=unit_scale,
+                   require_all_trim_cuts=require_all_trim_cuts,
+                   options=self._result_options, materials=self.materials)
+
+    def create_stock_image(self, stock: int, target, max_size: int = 1000) -> None:
+        from .exporters import render_png, render_svg
+        layout = self.get_stock_info(stock)
+        if isinstance(target, (str, Path)):
+            if Path(target).suffix.lower() == ".svg":
+                Path(target).write_text(render_svg(layout, linear=self.result.linear, max_size=max_size), encoding="utf-8")
+            else:
+                Path(target).write_bytes(render_png(layout, linear=self.result.linear, max_size=max_size))
+        else:
+            target.write(render_png(layout, linear=self.result.linear, max_size=max_size))
+
+    create_linear_stock_image = create_stock_image
+
+    def to_dict(self) -> dict:
+        """面向 Web 的任务结构，与版本化存档格式分别提供。"""
+        return {"stocks": [asdict(s) for s in self.stocks],
+                "parts": [asdict(p) for p in self.parts], "options": asdict(normalize_options(self.options)),
+                "materials": [asdict(m) for m in self.materials]}
+
+    @classmethod
+    def from_dict(cls, payload: dict) -> CutEngine:
+        if not isinstance(payload, dict) or set(payload) - {"stocks", "parts", "options", "materials"}:
+            raise ValidationError("任务必须包含 stocks、parts、options、materials 中的字段")
+        if not isinstance(payload.get("options", {}), dict):
+            raise ValidationError("options 必须是对象")
+        for name in ("stocks", "parts", "materials"):
+            if not isinstance(payload.get(name, []), list) or any(not isinstance(item, dict) for item in payload.get(name, [])):
+                raise ValidationError(f"{name} 必须是对象数组")
+        try:
+            engine = cls(**payload.get("options", {}))
+            for m in payload.get("materials", ()):
+                engine.add_material(**m)
+            engine._stocks = [Stock(**s) for s in payload.get("stocks", ())]
+            engine._parts = [Part(**p) for p in payload.get("parts", ())]
+            engine._stocks = [replace(s, width=number(s.width, "stock.width", positive=True),
+                                      height=number(s.height, "stock.height", positive=True)) for s in engine._stocks]
+            engine._parts = [replace(p, width=number(p.width, "part.width", positive=True),
+                                     height=number(p.height, "part.height", positive=True),
+                                     angle_start=number(p.angle_start, "angle_start"),
+                                     angle_end=number(p.angle_end, "angle_end")) for p in engine._parts]
+            return engine
+        except (TypeError, KeyError) as exc:
+            raise ValidationError(f"任务结构无效：{exc}") from exc
+
+    def to_json(self) -> str:
+        from .serialization import job_to_json
+        return job_to_json(self.stocks, self.parts, self.options, self.materials)
+
+    @classmethod
+    def from_json(cls, text: str) -> CutEngine:
+        from .serialization import job_from_json
+        return cls._from_job(job_from_json(text))
+
+    def to_xml(self) -> str:
+        from .serialization import job_to_xml
+        return job_to_xml(self.stocks, self.parts, self.options, self.materials)
+
+    @classmethod
+    def from_xml(cls, text: str) -> CutEngine:
+        from .serialization import job_from_xml
+        return cls._from_job(job_from_xml(text))
+
+    @classmethod
+    def _from_job(cls, job) -> CutEngine:
+        stocks, parts, options, materials = job
+        engine = cls(options)
+        engine._stocks, engine._parts, engine._materials = list(stocks), list(parts), list(materials)
+        return engine
+
+    def AddPart(self, width, height, count=1, rotatable=True, id="", material=-1):
+        if type(count) is bool:
+            count, rotatable = 1, count
+        return self.add_part(width, height, count, rotatable, id, material)
+
+    def AddLinearPart(self, length, count=1, *args):
+        if args and isinstance(args[0], str):
+            if len(args) > 2:
+                raise TypeError("AddLinearPart 参数过多")
+            return self.add_linear_part(length, count, id=args[0], material=args[1] if len(args) > 1 else -1)
+        if args:
+            if not 2 <= len(args) <= 4:
+                raise TypeError("斜角重载需要起始角和结束角")
+            return self.add_linear_part(length, count, angle_start=args[0], angle_end=args[1],
+                id=args[2] if len(args) > 2 else "", material=args[3] if len(args) > 3 else -1)
+        return self.add_linear_part(length, count)
+
+    def AddLinearStock(self, length, count=1, *args):
+        if len(args) == 1 and type(args[0]) is int:
+            return self.add_linear_stock(length, count, material=args[0])
+        if len(args) > 3:
+            raise TypeError("AddLinearStock 参数过多")
+        return self.add_linear_stock(length, count, id=args[0] if args else "",
+            waste=args[1] if len(args) > 1 else False, material=args[2] if len(args) > 2 else -1)
+
+
+# 旧接口名称集中声明，避免维护两套计算和查询逻辑。
+_METHOD_ALIASES = {
+    "Clear": "clear", "AddStock": "add_stock", "AddMaterial": "add_material",
+    "GetMaterial": "get_material", "Execute": "execute", "ExecuteLinear": "execute_linear",
+    "SetVerticalCutDirection": "set_vertical_cut_direction", "SetHorizontalCutDirection": "set_horizontal_cut_direction",
+    "SetAutoCutDirection": "set_auto_cut_direction", "ExportToCSV": "export_csv", "ExportToDXF": "export_dxf",
+    "ExportCutsToDXF": "export_cuts_dxf", "ExportToPTX": "export_ptx",
+    "CreateStockImage": "create_stock_image", "CreateLinearStockImage": "create_linear_stock_image",
+    "ExportToCSV_Stream": "export_csv", "ExportToDXF_Stream": "export_dxf",
+    "ExportCutsToDXF_Stream": "export_cuts_dxf", "ExportToPTX_Stream": "export_ptx",
+    "CreateStockImage_Stream": "create_stock_image", "CreateLinearStockImage_Stream": "create_linear_stock_image",
+}
+for _name, _value in tuple(vars(CutEngine).items()):
+    if _name.startswith("get_") or isinstance(_value, property):
+        _METHOD_ALIASES.setdefault(_pascal(_name), _name)
+for _alias, _original in _METHOD_ALIASES.items():
+    setattr(CutEngine, _alias, vars(CutEngine)[_original])
+CutEngine.Version = CutEngine.version