Skip to content

armgit / SOMA

Public Imported from GitHub
0

Desktop app for designing parametric 3D models in CadQuery together with the coding agent of your choice

13.0 KB
Raw Blame
"""Parameters: values of the model that the user can change in the app, in the Parameters panel.

    from soma import param

    BORE = param(38.0, "Cylinder bore", min=30, max=42, step=0.5, unit="mm", group="Crank train")
    TEETH = param(18, "Teeth", min=12, max=30)                        # whole number
    COUNTERWEIGHT = param(True, "Counterweight")                     # switch
    BEARING = param("sleeve", "Bearing", options=["sleeve", "ball"])  # choice

The first argument is the default. The user's values are kept in parameters.json in the project folder and take the
place of the defaults. Constants without param() stay internal and do not show up in the app.
"""
import ast
import inspect
import json
import math
import numbers
import re
from pathlib import Path

USER_FILE = "parameters.json"
FILE_NOTE = "Values the user set in the Parameters panel of SOMA. They take the place of the defaults of param() in the code."
KINDS = ("number", "int", "bool", "choice", "text")
MAX_TEXT = 1000

PARAMS = []        # je Build geleert (begin), Reihenfolge wie im Code
WARNINGS = []
_USER = None       # Werte aus parameters.json (Name -> Wert). None: noch nicht gelesen
_TREES = {}        # Syntaxbaeume je Datei, fuer den Namen der Konstante
_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")


def read_user_values(root):
    """Werte des Nutzers aus parameters.json und ggf. ein Hinweis, warum die Datei nicht gilt."""
    p = Path(root) / USER_FILE
    if not p.is_file():
        return {}, None
    try:
        data = json.loads(p.read_text(encoding="utf-8-sig"))  # -sig: von Hand gespeichert, oft mit BOM
    except (OSError, ValueError) as e:
        return {}, f"{USER_FILE} cannot be read ({e}). The defaults from the code apply."
    values = data.get("values") if isinstance(data, dict) else None
    if not isinstance(values, dict):
        return {}, f"{USER_FILE} has no \"values\" object. The defaults from the code apply."
    return {str(k): v for k, v in values.items()}, None


def begin(root):
    """Vor dem Ausfuehren des Modells (build.run_model): Liste leeren, Werte des Nutzers frisch lesen."""
    global _USER
    PARAMS.clear()
    WARNINGS.clear()
    _TREES.clear()
    _USER, problem = read_user_values(root)
    if problem:
        WARNINGS.append(problem)


def _assigned_name(file, line, col):
    """Name der Konstante, der der Aufruf zugewiesen wird (`BORE = param(...)`), sonst None."""
    tree = _TREES.get(file)
    if tree is None:
        try:
            tree = ast.parse(Path(file).read_text(encoding="utf-8"))
        except (OSError, SyntaxError, ValueError):
            tree = False
        _TREES[file] = tree
    if not tree:
        return None
    found = []
    for node in ast.walk(tree):
        if isinstance(node, (ast.Assign, ast.AnnAssign)) and isinstance(node.value, ast.Call) and node.value.lineno == line:
            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
            if len(targets) == 1 and isinstance(targets[0], ast.Name):
                found.append((node.value.col_offset, targets[0].id))
    exact = [n for c, n in found if c == col]
    if exact:
        return exact[0]
    return found[0][1] if len(found) == 1 else None


def _number(v, what):
    if isinstance(v, bool) or not isinstance(v, numbers.Real) or not math.isfinite(float(v)):
        raise ValueError(f"{what} must be a number, not {v!r}")
    return float(v)


def _scalar(v):
    """Wert, der so in JSON passt: Zahlen aus numpy werden zu int oder float."""
    if isinstance(v, (bool, str)):
        return v
    if isinstance(v, numbers.Integral):
        return int(v)
    if isinstance(v, numbers.Real) and math.isfinite(float(v)):
        return float(v)
    raise ValueError(f"options can only hold numbers, texts or True/False, not {v!r}")


def _same(a, b):
    """Gleicher Wert einer Auswahl. True und 1 sind hier verschieden, 8 und 8.0 nicht."""
    return a == b and isinstance(a, bool) == isinstance(b, bool)


def _spec(name, default, label, lo, hi, step, unit, options, group, help_):
    """Pruefen, was der Agent angegeben hat. Fehler hier sind Fehler im Code: mit klarer Meldung abbrechen."""
    where = f"param {name}"
    if options is not None:
        if isinstance(options, dict):
            opts = [dict(value=_scalar(k), label=str(v)) for k, v in options.items()]
        elif isinstance(options, (list, tuple)):
            opts = [dict(value=_scalar(v), label=str(v)) for v in options]
        else:
            raise ValueError(f"{where}: options must be a list of values (or a dict value -> label), not {type(options).__name__}")
        if not opts:
            raise ValueError(f"{where}: options must not be empty")
        if lo is not None or hi is not None or step is not None:
            raise ValueError(f"{where}: options and min/max/step do not go together")
        default = _scalar(default)
        if not any(_same(o["value"], default) for o in opts):
            raise ValueError(f"{where}: the default {default!r} is not one of the options")
        kind = "choice"
    elif isinstance(default, bool):
        kind, opts = "bool", None
    elif isinstance(default, numbers.Integral):
        kind, opts, default = "int", None, int(default)
    elif isinstance(default, numbers.Real):
        kind, opts, default = "number", None, _number(default, f"{where}: the default")
    elif isinstance(default, str):
        kind, opts = "text", None
        if len(default) > MAX_TEXT:
            raise ValueError(f"{where}: the default text is longer than {MAX_TEXT} characters")
    else:
        raise ValueError(f"{where}: the default must be a number, True/False or a text, not {type(default).__name__}. "
                         "For a choice pass options=[...]")
    if kind in ("bool", "text") and (lo is not None or hi is not None or step is not None):
        raise ValueError(f"{where}: min, max and step only work with numbers")
    if lo is not None:
        lo = _number(lo, f"{where}: min")
    if hi is not None:
        hi = _number(hi, f"{where}: max")
    if step is not None:
        step = _number(step, f"{where}: step")
        if step <= 0:
            raise ValueError(f"{where}: step must be greater than 0")
    if kind == "int":
        for v, what in ((lo, "min"), (hi, "max"), (step, "step")):
            if v is not None and v != int(v):
                raise ValueError(f"{where}: {what} must be a whole number like the default")
        lo, hi, step = (int(v) if v is not None else None for v in (lo, hi, step))
    if lo is not None and hi is not None and lo > hi:
        raise ValueError(f"{where}: min ({lo:g}) is greater than max ({hi:g})")
    if kind in ("number", "int") and lo is not None and default < lo:
        raise ValueError(f"{where}: the default {default:g} is less than min={lo:g}")
    if kind in ("number", "int") and hi is not None and default > hi:
        raise ValueError(f"{where}: the default {default:g} is greater than max={hi:g}")
    for v, what in ((label, "label"), (unit, "unit"), (group, "group"), (help_, "help")):
        if v is not None and not isinstance(v, str):
            raise ValueError(f"{where}: {what} must be a text, not {type(v).__name__}")
    label = (label or "").strip() or name.replace("_", " ").strip().capitalize()
    return dict(name=name, label=label, kind=kind, default=default, min=lo, max=hi, step=step,
                unit=(unit or "").strip() or None, options=opts, group=(group or "").strip() or None,
                help=(help_ or "").strip() or None)


def fmt(spec, v):
    """Wert mit Einheit fuer Meldungen: Zahlen mit Punkt, ohne ueberfluessige Nullen."""
    if isinstance(v, float):
        s = f"{v:.6f}".rstrip("0").rstrip(".")
    elif isinstance(v, str):
        s = repr(v)
    else:
        s = str(v)
    return f"{s} {spec['unit']}" if spec.get("unit") and spec["kind"] in ("number", "int") else s


def _coerce(spec, raw):
    """Wert aus parameters.json in den Typ des Parameters bringen. (Wert, None) oder (None, Grund)."""
    kind = spec["kind"]
    if kind in ("number", "int"):
        if isinstance(raw, str):  # von Hand eingetragen, etwa "40" oder "40,5"
            try:
                raw = float(raw.strip().replace(",", "."))
            except ValueError:
                return None, "not a number"
        if isinstance(raw, bool) or not isinstance(raw, (int, float)) or not math.isfinite(raw):
            return None, "not a number"
        if kind == "int":
            if raw != int(raw):
                return None, "not a whole number"
            return int(raw), None
        return float(raw), None
    if kind == "bool":
        return (raw, None) if isinstance(raw, bool) else (None, "not true or false")
    if kind == "text":
        if not isinstance(raw, str):
            return None, "not a text"
        return (raw, None) if len(raw) <= MAX_TEXT else (None, f"longer than {MAX_TEXT} characters")
    for o in spec["options"]:
        if _same(o["value"], raw):
            return o["value"], None
    return None, "not one of the options"


def param(default, label=None, *, min=None, max=None, step=None, unit=None, options=None, group=None, help=None, name=None):  # noqa: A002
    """A value the user can change in the app (Parameters panel). Returns the user's value or the default.

    default  the value from the code: a number (float or int), True/False or a text. The type decides the field
    label    name in the app, e.g. "Cylinder bore" (default: from the name of the constant)
    min, max range for numbers. Choose it so the model builds and makes sense over the whole range
    step     step for the slider and the arrow keys (int: whole numbers)
    unit     shown next to the value, e.g. "mm" or "deg"
    options  a choice instead of a free value: a list of values, or a dict value -> label
    group    heading in the app, e.g. "Crank train"
    help     one or two sentences shown in the app
    name     only needed when the call is not assigned to a constant (`BORE = param(...)` gives the name BORE)

    The user's values live in parameters.json (written by the app) and take the place of the default.
    """
    global _USER
    frame = inspect.currentframe().f_back
    pos = inspect.getframeinfo(frame, context=0).positions
    file = frame.f_code.co_filename
    line = pos.lineno if pos and pos.lineno else frame.f_lineno
    if name is None:
        name = _assigned_name(file, line, pos.col_offset if pos else None)
        if name is None:
            raise ValueError("param() needs a name: assign it to a constant (BORE = param(38.0, ...)) or pass name=\"BORE\"")
    elif not isinstance(name, str) or not _NAME.match(name):
        raise ValueError(f"name must look like a Python name (letters, digits, _), not {name!r}")
    spec = _spec(name, default, label, min, max, step, unit, options, group, help)
    for p in PARAMS:
        if p["name"] == name:
            # Dieselbe Stelle noch einmal (eine Animation importiert das Modell): derselbe Wert, kein zweiter Eintrag
            if (p["file"], p["line"]) == (file, line):
                return p["value"]
            raise ValueError(f"Parameter {name} is already defined in {Path(p['file']).name}, line {p['line']} (names must be unique)")
    if _USER is None:  # Modell ohne soma build ausgefuehrt (etwa importiert): Werte aus dem aktuellen Ordner
        _USER = read_user_values(Path.cwd())[0]
    value, source = spec["default"], "code"
    if name in _USER:
        raw = _USER[name]
        v, why = _coerce(spec, raw)
        if why:
            WARNINGS.append(f"{USER_FILE}: the value {raw!r} for {name} is {why}, the default from the code applies ({fmt(spec, spec['default'])}).")
        else:
            value, source = v, "user"
            lo, hi = spec["min"], spec["max"]
            if spec["kind"] in ("number", "int") and ((lo is not None and v < lo) or (hi is not None and v > hi)):
                WARNINGS.append(f"{name} = {fmt(spec, v)} (set in the app) lies outside the range {fmt(spec, lo) if lo is not None else '...'} "
                                f"to {fmt(spec, hi) if hi is not None else '...'} of the code. It is used anyway.")
    PARAMS.append(dict(spec, file=file, line=line, value=value, source=source))
    return value


def unused_warnings():
    """Werte in parameters.json, zu denen das Modell keinen Parameter (mehr) hat. Nur nach einem vollstaendigen Lauf."""
    known = {p["name"] for p in PARAMS}
    return [f"{USER_FILE} has a value for {n}, but the model has no parameter {n} (anymore). It is not used."
            for n in (_USER or {}) if n not in known]


def export(rel):
    """Liste fuer build.json und die App. `rel` macht Dateipfade relativ zum Projekt."""
    return [dict(p, file=rel(p["file"])) for p in PARAMS]


def summary(params):
    """Eine Zeile fuer `soma build`: Anzahl und die Werte, die der Nutzer gesetzt hat."""
    if not params:
        return None
    user = [p for p in params if p.get("source") == "user"]
    head = f"Parameters: {len(params)}"
    if not user:
        return f"{head}, all at the defaults from the code"
    return f"{head}, set by the user in the app: " + ", ".join(f"{p['name']} = {fmt(p, p['value'])} (code: {fmt(p, p['default'])})" for p in user)