liblaf.melon.io.wrap ¶

def load_landmarks(path: StrPath) -> Float[np.ndarray, "L 3"]:
    """Load Wrap landmark points from JSON.

    Non-JSON mesh paths are mapped to a sibling `.landmarks.json` file. Missing
    files return an empty `(0, 3)` array so annotation workflows can start from
    an unmarked mesh.

    Args:
        path: Landmark JSON file or mesh path whose landmark sidecar should be
            inferred.

    Returns:
        Landmark coordinates in `x`, `y`, `z` order.
    """
    path: Path = _infer_path(path)
    if not path.exists():
        return np.zeros((0, 3))
    with path.open() as fp:
        data: list[dict[str, float]] = json.load(fp)
    return np.asarray([[point["x"], point["y"], point["z"]] for point in data])

def load_polygons(path: StrPath) -> Integer[np.ndarray, " N"]:
    """Load selected polygon indices from JSON.

    Args:
        path: JSON file containing polygon indices.

    Returns:
        One-dimensional `int32` array of selected polygon indices. Missing files
        return an empty array.
    """
    path: Path = Path(path)
    if not path.exists():
        return np.empty((0,), np.int32)
    with path.open() as fp:
        data: list[int] = json.load(fp)
    polygons: Integer[np.ndarray, " N"] = np.asarray(data, np.int32)
    return polygons

def save_landmarks(landmarks: Float[ArrayLike, "L 3"], path: StrPath) -> None:
    """Save landmark points in Wrap-compatible JSON format.

    Args:
        landmarks: Array-like landmark coordinates with shape `(n, 3)`.
        path: Landmark JSON file or mesh path whose landmark sidecar should be
            inferred.
    """
    landmarks: Float[np.ndarray, "L 3"] = np.asarray(landmarks)
    path: Path = _infer_path(path)
    data: list[dict[str, float]] = [
        {"x": x, "y": y, "z": z} for x, y, z in landmarks.tolist()
    ]
    with path.open("w") as fp:
        json.dump(data, fp)

def save_polygons(
    polygons: Bool[ArrayLike, " full"] | Integer[ArrayLike, " selection"], path: StrPath
) -> None:
    """Save selected polygon indices for Wrap projects.

    Boolean masks are converted to their selected indices before serialization.

    Args:
        polygons: Boolean mask over all polygons or explicit polygon indices.
        path: JSON file to write.
    """
    path: Path = Path(path)
    polygons: Bool[np.ndarray, " full"] | Integer[np.ndarray, " selection"] = (
        np.asarray(polygons)
    )
    if np.isdtype(polygons.dtype, "bool"):
        polygons: Integer[np.ndarray, " selection"] = np.flatnonzero(polygons)
    with path.open("w") as fp:
        json.dump(polygons.tolist(), fp)