fbxkit 0.1.0__py3-none-any.whl

fbxkit/builtin_ops.py

@@ -0,0 +1,561 @@
+"""The operations that ship with fbxkit: the 增 / 删 / 改 of the title.
+
+Every one of them is written against :class:`~fbxkit.session.protocol.SessionProtocol`
+and nothing else, so all of them are exercised by the test suite with no SDK
+installed. None of them import ``fbx``.
+
+Three rules they all follow, and it is worth stating them once here rather than
+in each docstring:
+
+1. **Dry run computes the same answer.** An operation works out its changes
+   first and commits them second, so ``dry_run`` skips only the commit. A dry
+   run that disagrees with the real run is worse than not having one.
+2. **Setting a value to what it already holds is a noop, not a change.** The
+   report then says what actually happened rather than what was requested,
+   which is the difference between "47 nodes changed" and "47 nodes matched,
+   3 changed".
+3. **Deepest node first.** :func:`~fbxkit.ops.select_targets` sorts that way, so
+   editing a parent never invalidates a path the same batch is about to use.
+"""
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+from .errors import OperationError, ParamError
+from .ops import Operation, TargetedParams, register, select_targets
+from .schema import Change
+from .selectors import leaf_name, parent_path
+
+__all__ = []  # everything here is reached through the registry
+
+
+# --------------------------------------------------------------------------
+# 增 -- create
+# --------------------------------------------------------------------------
+@dataclass
+class CreateNodeParams:
+    name: str
+    parent: str = ""
+    type: str = "null"
+    exist_ok: bool = False
+
+    PARAM_HELP = {
+        "name": "name for the new node",
+        "parent": "path of the parent; empty means the scene root",
+        "type": "null, mesh, skeleton, camera, light",
+        "exist_ok": "return the existing node instead of failing when the path is taken",
+    }
+
+
+@register
+class CreateNodeOp(Operation):
+    """Add a node.
+
+    ``parent`` is an exact path, not a selector: creating "a child of every
+    mesh" is a different and much rarer intent than creating one node, and
+    conflating them makes the common case dangerous.
+    """
+
+    name = "create_node"
+    summary = "Create a node under an exact parent path"
+    params_class = CreateNodeParams
+
+    def run(self, session, params, ctx):
+        parent = params.parent
+        if parent and session.node_ref(parent) is None:
+            raise OperationError(
+                f"cannot create {params.name!r}: no parent node at {parent!r}"
+            )
+        wanted = f"{parent}|{params.name}"
+        if session.node_ref(wanted) is not None:
+            if params.exist_ok:
+                return []
+            raise OperationError(
+                f"a node already exists at {wanted!r}; FBX permits duplicate sibling "
+                "names, so this would create a second node reachable only as "
+                f"{wanted}#1 -- pass exist_ok=true if that is what you want"
+            )
+        if ctx.dry_run:
+            return [Change(kind="create", target=wanted, detail=params.type,
+                           before=None, after={"name": params.name, "type": params.type})]
+        created = session.create_node(parent, params.name, params.type)
+        return [Change(kind="create", target=created, detail=params.type,
+                       before=None, after={"name": params.name, "type": params.type})]
+
+
+# --------------------------------------------------------------------------
+# 删 -- delete
+# --------------------------------------------------------------------------
+@dataclass
+class DeleteNodeParams(TargetedParams):
+    recursive: bool = True
+
+    PARAM_HELP = dict(
+        TargetedParams.PARAM_HELP,
+        recursive=("delete descendants too (default true); false leaves them "
+                   "orphaned in the file, which is almost never what you want"),
+    )
+
+
+@register
+class DeleteNodeOp(Operation):
+    """Remove nodes, and by default everything under them.
+
+    ``recursive=False`` exists because the SDK offers it, not because it is a
+    good idea. Measured: a non-recursive destroy removes the node from the graph
+    but leaves its children alive in the scene, unparented and invisible to a
+    DAG walk -- and the exporter then writes them into the file as free-floating
+    objects. The operation reports that as a diagnostic rather than letting it
+    pass silently.
+    """
+
+    name = "delete_node"
+    summary = "Delete nodes matching a selector"
+    params_class = DeleteNodeParams
+
+    def run(self, session, params, ctx):
+        targets = select_targets(session, params.target, params.required)
+        # Shallowest first here, against the usual deepest-first order. Deletion
+        # is the one operation where acting on the ancestor *subsumes* the work
+        # on its descendants, so taking the parent first turns "|root|rig|**"
+        # into one reported change covering the subtree rather than one line per
+        # node. Every other operation wants deepest-first, which is why the
+        # default is that way round.
+        targets = sorted(targets, key=lambda ref: (ref.path.count("|"), ref.path))
+        changes = []
+        already_gone = set()
+        for ref in targets:
+            if ref.path in already_gone:
+                continue
+            info = session.node_info(ref.path)
+            doomed = [ref.path]
+            if params.recursive:
+                doomed = [n.path for n in session.iter_nodes()
+                          if n.path == ref.path or n.path.startswith(ref.path + "|")]
+            if not params.recursive and info.child_count:
+                ctx.note(
+                    f"{ref.path} kept {info.child_count} child node(s) alive but "
+                    "unparented; they stay in "
+                    "the file as free-floating objects"
+                )
+            if not ctx.dry_run:
+                doomed = session.delete_node(ref.path, recursive=params.recursive)
+            already_gone.update(doomed)
+            changes.append(
+                Change(kind="delete", target=ref.path,
+                       detail=f"{len(doomed)} node(s)",
+                       before={"type": ref.type, "removed": sorted(doomed)}, after=None)
+            )
+        return changes
+
+
+# --------------------------------------------------------------------------
+# 改 -- rename
+# --------------------------------------------------------------------------
+@dataclass
+class RenameParams(TargetedParams):
+    name: Optional[str] = None
+    pattern: Optional[str] = None
+    replacement: str = ""
+
+    PARAM_HELP = dict(
+        TargetedParams.PARAM_HELP,
+        name="the literal new name; only valid when the selector matches one node",
+        pattern="regular expression applied to each matched node's name",
+        replacement="what to substitute for pattern (supports \\1 backreferences)",
+    )
+
+
+@register
+class RenameOp(Operation):
+    """Rename nodes, literally or by regular expression.
+
+    Two modes because the two intents are genuinely different. ``name`` renames
+    one node and refuses to run against several -- giving twenty nodes the same
+    literal name is legal in FBX and produces twenty nodes nothing can address
+    individually, so it is treated as a mistake rather than performed. Batch
+    work uses ``pattern``/``replacement``, which gives each node a different
+    result by construction::
+
+        {"op": "rename", "target": "**[type=mesh]", "pattern": "^SM_", "replacement": ""}
+    """
+
+    name = "rename"
+    summary = "Rename nodes, literally or by regex substitution"
+    params_class = RenameParams
+
+    def run(self, session, params, ctx):
+        if (params.name is None) == (params.pattern is None):
+            raise ParamError(
+                "rename takes either 'name' (one node) or 'pattern' plus "
+                "'replacement' (many), not both and not neither"
+            )
+        targets = select_targets(session, params.target, params.required)
+        if params.name is not None and len(targets) > 1:
+            raise OperationError(
+                f"selector {params.target!r} matched {len(targets)} nodes and "
+                f"'name' would give them all the "
+                f"identical name {params.name!r}; use pattern/replacement for a batch "
+                "rename"
+            )
+        try:
+            compiled = re.compile(params.pattern) if params.pattern else None
+        except re.error as exc:
+            raise ParamError(f"rename: bad pattern {params.pattern!r}: {exc}") from exc
+
+        changes = []
+        for ref in targets:
+            if compiled is not None:
+                new_name = compiled.sub(params.replacement, ref.name)
+            else:
+                new_name = params.name
+            if new_name == ref.name:
+                continue
+            if not new_name:
+                raise OperationError(
+                    f"renaming {ref.path!r} would leave it with an empty name, which is "
+                    "legal in FBX but makes the node unaddressable by "
+                    "path"
+                )
+            if not ctx.dry_run:
+                session.rename_node(ref.path, new_name)
+            changes.append(
+                Change(kind="update", target=ref.path, detail="name",
+                       before=ref.name, after=new_name)
+            )
+        return changes
+
+
+# --------------------------------------------------------------------------
+# 改 -- reparent
+# --------------------------------------------------------------------------
+@dataclass
+class ReparentParams(TargetedParams):
+    parent: str = ""
+
+    PARAM_HELP = dict(
+        TargetedParams.PARAM_HELP,
+        parent="exact path of the new parent; empty means the scene root",
+    )
+
+
+@register
+class ReparentOp(Operation):
+    """Move nodes under a different parent."""
+
+    name = "reparent"
+    summary = "Move nodes under a new parent"
+    params_class = ReparentParams
+
+    def run(self, session, params, ctx):
+        if params.parent and session.node_ref(params.parent) is None:
+            raise OperationError(f"no parent node at {params.parent!r}")
+        targets = select_targets(session, params.target, params.required)
+        changes = []
+        for ref in targets:
+            if ref.parent_path == params.parent:
+                continue
+            if params.parent == ref.path or params.parent.startswith(ref.path + "|"):
+                raise OperationError(
+                    f"cannot reparent {ref.path!r} under {params.parent!r}: "
+                    "that would make the node its "
+                    "own ancestor"
+                )
+            if not ctx.dry_run:
+                session.reparent_node(ref.path, params.parent)
+            changes.append(
+                Change(kind="update", target=ref.path, detail="parent",
+                       before=ref.parent_path, after=params.parent)
+            )
+        return changes
+
+
+# --------------------------------------------------------------------------
+# 改 -- properties
+# --------------------------------------------------------------------------
+@dataclass
+class SetPropertyParams(TargetedParams):
+    name: str = ""
+    value: Any = None
+
+    PARAM_HELP = dict(
+        TargetedParams.PARAM_HELP,
+        name="property name, e.g. 'Lcl Translation' or 'Visibility'",
+        value="the new value; a list for vector properties",
+    )
+
+
+@register
+class SetPropertyOp(Operation):
+    """Set an existing property on every matched node."""
+
+    name = "set_property"
+    summary = "Set a property on matching nodes"
+    params_class = SetPropertyParams
+
+    def run(self, session, params, ctx):
+        if not params.name:
+            raise ParamError("set_property requires a non-empty 'name'")
+        targets = select_targets(session, params.target, params.required)
+        changes = []
+        for ref in targets:
+            old = session.get_property(ref.path, params.name)
+            if _same(old, params.value):
+                continue
+            if not ctx.dry_run:
+                session.set_property(ref.path, params.name, params.value)
+            changes.append(
+                Change(kind="update", target=ref.path, detail=params.name,
+                       before=old, after=params.value)
+            )
+        return changes
+
+
+@dataclass
+class AddPropertyParams(TargetedParams):
+    name: str = ""
+    type: str = "String"
+    value: Any = None
+
+    PARAM_HELP = dict(
+        TargetedParams.PARAM_HELP,
+        name="name for the new user-defined property",
+        type="String, Bool, Integer, Double or Double3",
+        value="its initial value",
+    )
+
+
+@register
+class AddPropertyOp(Operation):
+    """Attach a user-defined property -- the usual way pipeline metadata rides along."""
+
+    name = "add_property"
+    summary = "Add a user-defined property to matching nodes"
+    params_class = AddPropertyParams
+
+    def run(self, session, params, ctx):
+        if not params.name:
+            raise ParamError("add_property requires a non-empty 'name'")
+        targets = select_targets(session, params.target, params.required)
+        changes = []
+        for ref in targets:
+            if not ctx.dry_run:
+                session.create_property(ref.path, params.name, params.type, params.value)
+            changes.append(
+                Change(kind="create", target=ref.path, detail=params.name,
+                       before=None, after=params.value)
+            )
+        return changes
+
+
+@dataclass
+class RemovePropertyParams(TargetedParams):
+    name: str = ""
+
+    PARAM_HELP = dict(TargetedParams.PARAM_HELP,
+                      name="name of the user-defined property to remove")
+
+
+@register
+class RemovePropertyOp(Operation):
+    """Remove a user-defined property. Built-ins are refused, not silently skipped."""
+
+    name = "remove_property"
+    summary = "Remove a user-defined property from matching nodes"
+    params_class = RemovePropertyParams
+
+    def run(self, session, params, ctx):
+        if not params.name:
+            raise ParamError("remove_property requires a non-empty 'name'")
+        targets = select_targets(session, params.target, params.required)
+        changes = []
+        for ref in targets:
+            existing = [p for p in session.properties(ref.path, user_only=True)
+                        if p.name == params.name]
+            if not existing:
+                # A property that is not there is nothing to remove -- a noop.
+                # A *built-in* one that is there is a different thing entirely:
+                # the request can never succeed, so it is a caller mistake and
+                # gets said out loud rather than silently counted as done.
+                builtin = [p for p in session.properties(ref.path)
+                           if p.name == params.name]
+                if builtin:
+                    raise OperationError(
+                        f"{params.name!r} on {ref.path!r} is a built-in "
+                        "property and cannot be "
+                        "removed; only user-defined properties can"
+                    )
+                continue
+            if not ctx.dry_run:
+                old = session.remove_property(ref.path, params.name)
+            else:
+                old = existing[0].value
+            changes.append(
+                Change(kind="delete", target=ref.path, detail=params.name,
+                       before=old, after=None)
+            )
+        return changes
+
+
+# --------------------------------------------------------------------------
+# 改 -- transform convenience
+# --------------------------------------------------------------------------
+@dataclass
+class SetTransformParams(TargetedParams):
+    translation: Optional[List[float]] = None
+    rotation: Optional[List[float]] = None
+    scaling: Optional[List[float]] = None
+
+    PARAM_HELP = dict(
+        TargetedParams.PARAM_HELP,
+        translation="[x, y, z] local translation",
+        rotation="[x, y, z] local rotation in degrees",
+        scaling="[x, y, z] local scaling",
+    )
+
+
+@register
+class SetTransformOp(Operation):
+    """Set local transform components, skipping the ones left as null.
+
+    Sugar over three ``set_property`` calls, but the sugar is the point: the FBX
+    property names are ``Lcl Translation`` / ``Lcl Rotation`` / ``Lcl Scaling``,
+    with the space and the abbreviation, and getting one wrong is a silent
+    no-match rather than an error at the call site.
+    """
+
+    name = "set_transform"
+    summary = "Set local translation / rotation / scaling"
+    params_class = SetTransformParams
+
+    _FIELDS = (("translation", "Lcl Translation"),
+               ("rotation", "Lcl Rotation"),
+               ("scaling", "Lcl Scaling"))
+
+    def run(self, session, params, ctx):
+        wanted = [(prop, getattr(params, attr))
+                  for attr, prop in self._FIELDS if getattr(params, attr) is not None]
+        if not wanted:
+            raise ParamError(
+                "set_transform needs at least one of translation, rotation, scaling"
+            )
+        for prop, value in wanted:
+            if len(value) != 3:
+                raise ParamError(
+                    f"{prop} takes 3 numbers, got {len(value)}"
+                )
+        targets = select_targets(session, params.target, params.required)
+        changes = []
+        for ref in targets:
+            for prop, value in wanted:
+                old = session.get_property(ref.path, prop)
+                if _same(old, value):
+                    continue
+                if not ctx.dry_run:
+                    session.set_property(ref.path, prop, value)
+                changes.append(
+                    Change(kind="update", target=ref.path, detail=prop,
+                           before=old, after=list(value))
+                )
+        return changes
+
+
+# --------------------------------------------------------------------------
+# 改 -- textures
+# --------------------------------------------------------------------------
+@dataclass
+class RetargetTexturesParams:
+    pattern: str = ""
+    replacement: str = ""
+    prefix: Optional[str] = None
+    only_missing: bool = False
+    required: bool = True
+
+    PARAM_HELP = {
+        "pattern": "regular expression matched against each texture's path",
+        "replacement": "what to substitute (supports \\1 backreferences)",
+        "prefix": "alternatively, rebase every texture onto this directory",
+        "only_missing": "touch only textures whose file does not currently exist",
+        "required": "fail when no texture matches (default true)",
+    }
+
+
+@register
+class RetargetTexturesOp(Operation):
+    """Rewrite texture paths -- the single most common thing wrong with a delivered FBX.
+
+    A texture path that resolved on the artist's machine and nowhere else is
+    invisible until something looks, so this operation reports, for each texture
+    it rewrites, whether the new path actually exists on disk. A batch that
+    repoints two hundred textures at a directory that is empty is a batch that
+    should say so.
+    """
+
+    name = "retarget_textures"
+    summary = "Rewrite texture file paths by regex or by rebasing onto a directory"
+    params_class = RetargetTexturesParams
+
+    def run(self, session, params, ctx):
+        if bool(params.pattern) == bool(params.prefix):
+            raise ParamError(
+                "retarget_textures takes either 'pattern' (with 'replacement') or "
+                "'prefix', not both and not neither"
+            )
+        try:
+            compiled = re.compile(params.pattern) if params.pattern else None
+        except re.error as exc:
+            raise ParamError(
+                f"retarget_textures: bad pattern {params.pattern!r}: {exc}"
+            ) from exc
+
+        textures = session.textures()
+        if params.only_missing:
+            textures = [t for t in textures if not t.exists]
+        if not textures and params.required:
+            raise OperationError(
+                "no {}textures in this scene".format("missing " if params.only_missing else "")
+            )
+
+        changes = []
+        for tex in textures:
+            if compiled is not None:
+                new_path = compiled.sub(params.replacement, tex.filename)
+            else:
+                new_path = os.path.join(params.prefix, os.path.basename(tex.filename))
+                new_path = new_path.replace("\\", "/")
+            if new_path == tex.filename:
+                continue
+            if not ctx.dry_run:
+                session.set_texture_filename(tex.name, new_path)
+            if not os.path.isfile(new_path):
+                ctx.note(
+                    f"texture {tex.name!r} now points at {new_path!r}, which "
+                    "does not exist on this "
+                    "machine"
+                )
+            changes.append(
+                Change(kind="update", target=tex.name, detail="filename",
+                       before=tex.filename, after=new_path)
+            )
+        return changes
+
+
+def _same(old, new):
+    # type: (Any, Any) -> bool
+    """Would writing ``new`` over ``old`` change anything?
+
+    Compares numerically where both sides are numbers, so a JSON patch carrying
+    ``1`` does not read as a change against a stored ``1.0`` and inflate every
+    report with edits that did nothing.
+    """
+    if isinstance(old, (list, tuple)) and isinstance(new, (list, tuple)):
+        if len(old) != len(new):
+            return False
+        return all(_same(a, b) for a, b in zip(old, new))
+    if isinstance(old, bool) or isinstance(new, bool):
+        return bool(old) == bool(new)
+    if isinstance(old, (int, float)) and isinstance(new, (int, float)):
+        return float(old) == float(new)
+    return old == new