yaplotlib 0.1.2__tar.gz → 1.0.0__tar.gz

yaplotlib-1.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: yaplotlib
+Version: 1.0.0
+Summary: A tiny library to generate Yaplot file.
+License: MIT
+Author: vitroid
+Author-email: vitroid@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: numpy (>=1.24)
+Description-Content-Type: text/markdown
+
+## yaplotlib
+
+Yaplot 形式の描画データを Python から作るライブラリです。
+
+描画コマンドは種類（`line` や `circle` など）と座標の列で表します。種類ごとの違いはライブラリ内部の表にまとめてあり、呼び出し側は同じ `add` を使います。複数フレームと、ファイル先頭の `global` ブロック、画面に固定する SVG は `YaplotDocument` が持ちます。
+
+## インストール
+
+```bash
+pip install yaplotlib
+```
+
+numpy が必要です。
+
+## クイックスタート
+
+```python
+import numpy as np
+from yaplotlib import YaplotDocument
+
+doc = YaplotDocument()
+doc.globals.fov = 30
+doc.globals.radius = 0.3
+
+xyz = np.array([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
+path = np.array([[0.0, 0.0, 0.0], [0.5, 0.2, 0.0], [1.0, 0.0, 0.0]])
+
+for t in range(len(path)):
+    frame = doc.new_frame()
+    frame.add_many("circle", xyz, color=3)
+    frame.add("stick", (0, 0, 0), (1, 0, 0), arrow=1, color=4)
+    if t >= 1:
+        # polyline は、Yaplot が受け付けるようになるまで線分に分解して出力する
+        frame.add("polyline", *path[: t + 1], color=5)
+    frame.add("text", (0, 0, 0), text=f"t = {t}")
+
+doc.save("movie.yap")
+```
+
+`color`、`layer`、`radius`、`arrow` を省略すると、その項目は出力されません。直前の値を引き継ぐので、色を指定した要素の後ろに置いた色なしの要素は、その色で描かれます。
+
+## global ブロック
+
+`doc.globals` に置いた値は、すべてのフレームの初期状態になります。何も設定しなければ `global` ブロックは出力しません。
+
+- 見た目: `layer`, `color`, `radius`, `arrow`, `palettes`
+- 表示の初期状態: `reality`（0..4）, `splat`（0..3）, `fov`, `verbose`（0..3）, `thickness`, `rotation`（1〜3 個の数値）, `fps`, `hide`, `show`, `messages`
+- 全フレーム共通の SVG: `add_svg`
+
+```python
+doc.globals.reality = 3
+doc.globals.palettes[3] = (255, 100, 100)
+doc.globals.messages.append("loaded")
+```
+
+## SVG
+
+画面に固定する 2D の情報（見出し、凡例、グラフ）は SVG のまま渡します。`global` に置くと全フレーム、フレームに置くとそのフレームだけに出ます。matplotlib の Figure も渡せます（背景は透明になります）。
+
+```python
+frame.add_svg('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">'
+              '<text x="16" y="32" fill="white">t = 0</text></svg>')
+frame.add_svg(figure)          # matplotlib の Figure
+doc.globals.add_svg("hud.svg")  # ファイル
+```
+
+## まとめて追加する
+
+`add_many` は座標を ndarray のまま保持します。形は「個数 N × 1 個あたりの座標数 × 3」です。
+
+| 種類 | 形 |
+|---|---|
+| `circle`, `ring`, `triangle`, `square`, `pentagon`, `hexagon`, `text` | `(N, 3)` |
+| `line`, `stick` | `(N, 2, 3)` |
+| `polygon`, `polyline`（頂点数がそろうとき） | `(N, m, 3)` |
+
+`line` の始点と終点が別の配列なら `np.stack([starts, ends], axis=1)` で重ねます。`text` には長さ N の `texts` も渡します。
+
+```python
+starts = np.zeros((10, 3))
+ends = np.ones((10, 3))
+frame.add_many("line", np.stack([starts, ends], axis=1), color=3)
+```
+
+## パレット
+
+```python
+from yaplotlib.palettes import rainbow_colors
+
+doc.globals.palettes.update(enumerate(rainbow_colors(8), start=10))
+frame.palette(3, (255, 96, 96))
+frame.palettes(rainbow_colors(8), offset=10)
+```
+
+`random_colors` と `gradation_colors` も同じように RGB のリストを返します。
+
+## 以前の API
+
+モジュールの関数（`Line`, `Circle`, `Color`, `SetPalette` など）と、`Line` や `Color` のような大文字のメソッドは、`DeprecationWarning` を出して残してあります。`Yaplot` は 1 フレームだけの `YaplotFrame` の別名です。
+
+```python
+from yaplotlib import Yaplot
+
+drawing = Yaplot()
+drawing.Points([(0, 0, 0), (1, 0, 0)], color=2, size=0.3)
+drawing.save("example.yaplot")
+```
+
+## ライセンス
+
+本リポジトリの `LICENSE` ファイルを参照してください。
+

yaplotlib-1.0.0/README.md

@@ -0,0 +1,111 @@
+## yaplotlib
+
+Yaplot 形式の描画データを Python から作るライブラリです。
+
+描画コマンドは種類（`line` や `circle` など）と座標の列で表します。種類ごとの違いはライブラリ内部の表にまとめてあり、呼び出し側は同じ `add` を使います。複数フレームと、ファイル先頭の `global` ブロック、画面に固定する SVG は `YaplotDocument` が持ちます。
+
+## インストール
+
+```bash
+pip install yaplotlib
+```
+
+numpy が必要です。
+
+## クイックスタート
+
+```python
+import numpy as np
+from yaplotlib import YaplotDocument
+
+doc = YaplotDocument()
+doc.globals.fov = 30
+doc.globals.radius = 0.3
+
+xyz = np.array([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
+path = np.array([[0.0, 0.0, 0.0], [0.5, 0.2, 0.0], [1.0, 0.0, 0.0]])
+
+for t in range(len(path)):
+    frame = doc.new_frame()
+    frame.add_many("circle", xyz, color=3)
+    frame.add("stick", (0, 0, 0), (1, 0, 0), arrow=1, color=4)
+    if t >= 1:
+        # polyline は、Yaplot が受け付けるようになるまで線分に分解して出力する
+        frame.add("polyline", *path[: t + 1], color=5)
+    frame.add("text", (0, 0, 0), text=f"t = {t}")
+
+doc.save("movie.yap")
+```
+
+`color`、`layer`、`radius`、`arrow` を省略すると、その項目は出力されません。直前の値を引き継ぐので、色を指定した要素の後ろに置いた色なしの要素は、その色で描かれます。
+
+## global ブロック
+
+`doc.globals` に置いた値は、すべてのフレームの初期状態になります。何も設定しなければ `global` ブロックは出力しません。
+
+- 見た目: `layer`, `color`, `radius`, `arrow`, `palettes`
+- 表示の初期状態: `reality`（0..4）, `splat`（0..3）, `fov`, `verbose`（0..3）, `thickness`, `rotation`（1〜3 個の数値）, `fps`, `hide`, `show`, `messages`
+- 全フレーム共通の SVG: `add_svg`
+
+```python
+doc.globals.reality = 3
+doc.globals.palettes[3] = (255, 100, 100)
+doc.globals.messages.append("loaded")
+```
+
+## SVG
+
+画面に固定する 2D の情報（見出し、凡例、グラフ）は SVG のまま渡します。`global` に置くと全フレーム、フレームに置くとそのフレームだけに出ます。matplotlib の Figure も渡せます（背景は透明になります）。
+
+```python
+frame.add_svg('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">'
+              '<text x="16" y="32" fill="white">t = 0</text></svg>')
+frame.add_svg(figure)          # matplotlib の Figure
+doc.globals.add_svg("hud.svg")  # ファイル
+```
+
+## まとめて追加する
+
+`add_many` は座標を ndarray のまま保持します。形は「個数 N × 1 個あたりの座標数 × 3」です。
+
+| 種類 | 形 |
+|---|---|
+| `circle`, `ring`, `triangle`, `square`, `pentagon`, `hexagon`, `text` | `(N, 3)` |
+| `line`, `stick` | `(N, 2, 3)` |
+| `polygon`, `polyline`（頂点数がそろうとき） | `(N, m, 3)` |
+
+`line` の始点と終点が別の配列なら `np.stack([starts, ends], axis=1)` で重ねます。`text` には長さ N の `texts` も渡します。
+
+```python
+starts = np.zeros((10, 3))
+ends = np.ones((10, 3))
+frame.add_many("line", np.stack([starts, ends], axis=1), color=3)
+```
+
+## パレット
+
+```python
+from yaplotlib.palettes import rainbow_colors
+
+doc.globals.palettes.update(enumerate(rainbow_colors(8), start=10))
+frame.palette(3, (255, 96, 96))
+frame.palettes(rainbow_colors(8), offset=10)
+```
+
+`random_colors` と `gradation_colors` も同じように RGB のリストを返します。
+
+## 以前の API
+
+モジュールの関数（`Line`, `Circle`, `Color`, `SetPalette` など）と、`Line` や `Color` のような大文字のメソッドは、`DeprecationWarning` を出して残してあります。`Yaplot` は 1 フレームだけの `YaplotFrame` の別名です。
+
+```python
+from yaplotlib import Yaplot
+
+drawing = Yaplot()
+drawing.Points([(0, 0, 0), (1, 0, 0)], color=2, size=0.3)
+drawing.save("example.yaplot")
+```
+
+## ライセンス
+
+本リポジトリの `LICENSE` ファイルを参照してください。

yaplotlib-1.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+[tool.poetry]
+name = "yaplotlib"
+version = "1.0.0"
+description = "A tiny library to generate Yaplot file."
+authors = ["vitroid <vitroid@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+numpy = ">=1.24"
+
+[tool.poetry.group.dev.dependencies]
+pdoc = "^15.0"
+pytest = ">=8"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+filterwarnings = ["always::DeprecationWarning"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

yaplotlib-1.0.0/yaplotlib/__init__.py

@@ -0,0 +1,61 @@
+"""Yaplot 形式の描画データを作る。"""
+
+# even: stable; odd: develop
+__version__ = "1.0.0"
+
+from .core import (
+    Arrow,
+    ArrowType,
+    Circle,
+    Color,
+    Layer,
+    Line,
+    NewPage,
+    Polygon,
+    SetPalette,
+    Size,
+    Text,
+)
+from .document import YaplotDocument
+from .elements import Batch, PaletteDef, Primitive, Svg
+from .frame import Yaplot, YaplotFrame
+from .globals import Globals
+from .palettes import (
+    GradationPalettes,
+    RainbowPalettes,
+    RandomPalettes,
+    gradation_colors,
+    rainbow_colors,
+    random_colors,
+)
+from .spec import Kind
+
+__all__ = [
+    "__version__",
+    "Kind",
+    "Primitive",
+    "Batch",
+    "PaletteDef",
+    "Svg",
+    "Globals",
+    "YaplotFrame",
+    "Yaplot",
+    "YaplotDocument",
+    "random_colors",
+    "rainbow_colors",
+    "gradation_colors",
+    "Line",
+    "Text",
+    "Circle",
+    "Arrow",
+    "Polygon",
+    "Color",
+    "SetPalette",
+    "Size",
+    "Layer",
+    "ArrowType",
+    "NewPage",
+    "RandomPalettes",
+    "RainbowPalettes",
+    "GradationPalettes",
+]

yaplotlib-1.0.0/yaplotlib/_writer.py

@@ -0,0 +1,356 @@
+"""要素の列を Yaplot のテキストに変換する。
+
+状態（レイヤ・色・半径・矢印）の差分はここでだけ計算する。
+フレームは状態を持たない。
+"""
+
+import operator
+from typing import Optional, Sequence, Union
+
+import numpy as np
+
+from .elements import (
+    Batch,
+    FrameBreak,
+    PaletteDef,
+    Primitive,
+    Svg,
+    _as_int,
+    _as_radius,
+)
+from .globals import Globals
+from .spec import KINDS
+
+# Yaplot 本体の初期値。色だけは線が 0、塗りが 2 と分かれているため未確定にする。
+_DEFAULT_LAYER = 1
+_DEFAULT_RADIUS = 1.0
+_DEFAULT_ARROW = 0
+
+
+def quote_text(text: str) -> str:
+    """空白や引用符を含む文字列を Yaplot の ``"..."`` にする。"""
+    if "\n" in text or "\r" in text:
+        raise ValueError("改行を含む文字列は出力できません")
+    if text == "" or any(char.isspace() or char in '"\\' for char in text):
+        escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    return text
+
+
+def format_command(
+    command: str,
+    points: Sequence[Sequence[float]],
+    *,
+    count: bool = False,
+    text: Optional[str] = None,
+) -> str:
+    """描画コマンド 1 行を作る。座標の末尾には従来どおり空白を付ける。"""
+    parts = [command]
+    if count:
+        parts.append(str(len(points)))
+    for point in points:
+        for coord in point:
+            parts.append(f"{float(coord):.4f}")
+    line = " ".join(parts) + " "
+    if text is not None:
+        line += " " + quote_text(text)
+    return line + "\n"
+
+
+def format_palette(index: int, rgb: Sequence[int]) -> str:
+    """``@ n r g b`` の 1 行を作る。"""
+    red, green, blue = rgb
+    return f"@ {int(index)} {int(red)} {int(green)} {int(blue)}\n"
+
+
+class _State:
+    """書き出し中の、Yaplot 側の現在の状態。"""
+
+    def __init__(self, defaults: Optional[Globals]) -> None:
+        self.layer = _DEFAULT_LAYER
+        self.radius = _DEFAULT_RADIUS
+        self.arrow = _DEFAULT_ARROW
+        self.color: Optional[int] = None
+        if defaults is not None:
+            if defaults.layer is not None:
+                self.layer = _as_int("layer", defaults.layer, 1)
+            if defaults.radius is not None:
+                self.radius = _as_radius(defaults.radius)
+            if defaults.arrow is not None:
+                self.arrow = _as_int("arrow", defaults.arrow, 0)
+            self.color = _opening_color(defaults)
+        self._initial = (self.layer, self.radius, self.arrow, self.color)
+
+    def reset(self) -> None:
+        self.layer, self.radius, self.arrow, self.color = self._initial
+
+
+def _opening_color(defaults: Globals) -> Optional[int]:
+    """global ブロックを読み終えた時点で選ばれている色。"""
+    if defaults.color is not None:
+        return _as_int("color", defaults.color, 0)
+    if not defaults.palettes:
+        return None
+    last = sorted(defaults.palettes)[-1]
+    return _as_int("palette", last, 0)
+
+
+def _lowering(kind: str, lower: bool) -> bool:
+    spec = KINDS[kind]
+    if lower and spec.lower_to:
+        return True
+    if spec.command is None:
+        raise ValueError(
+            f"{kind!r} にはまだ Yaplot のコマンドがありません。"
+            " dumps(lower=True) で線分に分解して出力できます。"
+        )
+    return False
+
+
+def _emit_style(state: _State, item: Union[Primitive, Batch], out: list[str]) -> None:
+    if item.layer is not None and item.layer != state.layer:
+        state.layer = item.layer
+        out.append(f"y {state.layer}\n")
+    if item.color is not None and item.color != state.color:
+        state.color = item.color
+        out.append(f"@ {state.color}\n")
+    if item.radius is not None and item.radius != state.radius:
+        state.radius = item.radius
+        out.append(f"r {state.radius}\n")
+    if item.arrow is not None and item.arrow != state.arrow:
+        state.arrow = item.arrow
+        out.append(f"a {state.arrow}\n")
+
+
+def _emit_primitive(state: _State, prim: Primitive, out: list[str], lower: bool) -> None:
+    spec = KINDS[prim.kind]
+    _emit_style(state, prim, out)
+    if _lowering(prim.kind, lower):
+        command = KINDS[spec.lower_to].command  # type: ignore[index]
+        points = prim.points
+        for start, end in zip(points, points[1:]):
+            out.append(format_command(command or "", (start, end)))
+        return
+    out.append(
+        format_command(
+            spec.command or "",
+            prim.points,
+            count=spec.npoints is None,
+            text=prim.text,
+        )
+    )
+
+
+def _emit_batch(state: _State, batch: Batch, out: list[str], lower: bool) -> None:
+    spec = KINDS[batch.kind]
+    lowering = _lowering(batch.kind, lower)
+    _emit_style(state, batch, out)
+    if lowering:
+        command = KINDS[spec.lower_to].command or ""  # type: ignore[union-attr]
+        if isinstance(batch.coords, np.ndarray):
+            out.append(_format_block(command, _chains_to_lines(batch.coords), None, False))
+        else:
+            for array in batch.coords:
+                for index in range(array.shape[0] - 1):
+                    out.append(format_command(command, (array[index], array[index + 1])))
+        return
+    if isinstance(batch.coords, np.ndarray):
+        out.append(
+            _format_block(spec.command or "", batch.coords, batch.texts, spec.npoints is None)
+        )
+        return
+    for index, array in enumerate(batch.coords):
+        text = None if batch.texts is None else batch.texts[index]
+        out.append(format_command(spec.command or "", array, count=True, text=text))
+
+
+def _emit_palette(state: _State, item: PaletteDef, out: list[str]) -> None:
+    out.append(format_palette(item.index, item.rgb))
+    # @ n r g b はパレット n を現在の色としても選ぶ。
+    state.color = item.index
+
+
+def _chains_to_lines(coords: np.ndarray) -> np.ndarray:
+    """(N, m, 3) の折れ線を、隣り合う頂点を結ぶ (N*(m-1), 2, 3) の線分にする。"""
+    if coords.shape[0] == 0 or coords.shape[1] < 2:
+        return np.zeros((0, 2, 3), dtype=float)
+    paired = np.stack((coords[:, :-1, :], coords[:, 1:, :]), axis=2)
+    return paired.reshape(-1, 2, 3)
+
+
+def _format_block(
+    command: str,
+    coords: np.ndarray,
+    texts: Optional[tuple[str, ...]],
+    with_count: bool,
+) -> str:
+    """(N, k, 3) をコマンドの行にまとめて整形する。"""
+    count = int(coords.shape[0])
+    if count == 0:
+        return ""
+    width = int(coords.shape[1])
+    formatted = np.char.mod("%.4f", coords.reshape(count, width * 3))
+    prefix = f"{command} {width} " if with_count else f"{command} "
+    lines: list[str] = []
+    for index in range(count):
+        line = prefix + " ".join(formatted[index].tolist()) + " "
+        if texts is not None:
+            line += " " + quote_text(texts[index])
+        lines.append(line + "\n")
+    return "".join(lines)
+
+
+def _svg_text(svg: Svg) -> str:
+    text = svg.text
+    if not text.endswith("\n"):
+        return text + "\n"
+    return text
+
+
+def render_frame(
+    items: Sequence[object],
+    svgs: Sequence[Svg],
+    defaults: Optional[Globals],
+    lower: bool = True,
+) -> str:
+    """1 フレーム分をテキストにする。末尾にフレーム区切りの空行は付けない。"""
+    state = _State(defaults)
+    out: list[str] = []
+    for item in items:
+        if isinstance(item, FrameBreak):
+            out.append("\n")
+            state.reset()
+            continue
+        if isinstance(item, PaletteDef):
+            _emit_palette(state, item, out)
+        elif isinstance(item, Batch):
+            _emit_batch(state, item, out, lower)
+        elif isinstance(item, Primitive):
+            _emit_primitive(state, item, out, lower)
+        else:
+            raise TypeError(f"フレームに置けない要素です: {type(item).__name__}")
+    for svg in svgs:
+        out.append(_svg_text(svg))
+    return "".join(out)
+
+
+def _join_frames(texts: Sequence[str]) -> str:
+    out: list[str] = []
+    last = len(texts) - 1
+    for index, text in enumerate(texts):
+        if text and not text.endswith("\n"):
+            text += "\n"
+        out.append(text)
+        if index != last:
+            out.append("\n")
+    return "".join(out)
+
+
+def render_document(defaults: Globals, frames: Sequence[object], lower: bool = True) -> str:
+    """global ブロックと全フレームを 1 つのテキストにする。"""
+    parts: list[str] = []
+    if not defaults.is_empty():
+        parts.append(render_globals(defaults))
+    rendered = [
+        render_frame(frame.items, frame.svgs, defaults, lower)  # type: ignore[attr-defined]
+        for frame in frames
+    ]
+    parts.append(_join_frames(rendered))
+    return "".join(parts)
+
+
+def render_globals(defaults: Globals) -> str:
+    """global ブロックを、終端の空行まで含めて作る。"""
+    lines = ["global\n"]
+    if defaults.reality is not None:
+        lines.append(f"reality {_int_between('reality', defaults.reality, 0, 4)}\n")
+    if defaults.splat is not None:
+        lines.append(f"splat {_int_between('splat', defaults.splat, 0, 3)}\n")
+    if defaults.fov is not None:
+        lines.append(f"fov {_float_token(_as_float('fov', defaults.fov))}\n")
+    if defaults.verbose is not None:
+        lines.append(f"verbose {_int_between('verbose', defaults.verbose, 0, 3)}\n")
+    if defaults.thickness is not None:
+        lines.append(f"thickness {_plain_int('thickness', defaults.thickness)}\n")
+    if defaults.rotation is not None:
+        lines.append("rotation " + _rotation(defaults.rotation) + "\n")
+    if defaults.fps is not None:
+        lines.append(f"fps {_float_token(_as_float('fps', defaults.fps))}\n")
+    if defaults.hide:
+        lines.append("hide " + _layers("hide", defaults.hide) + "\n")
+    if defaults.show:
+        lines.append("show " + _layers("show", defaults.show) + "\n")
+    for message in defaults.messages:
+        if not isinstance(message, str):
+            raise TypeError("message は文字列にしてください")
+        lines.append("message " + quote_text(message) + "\n")
+    if defaults.radius is not None:
+        lines.append(f"r {_as_radius(defaults.radius)}\n")
+    if defaults.layer is not None:
+        lines.append(f"y {_as_int('layer', defaults.layer, 1)}\n")
+    if defaults.arrow is not None:
+        lines.append(f"a {_as_int('arrow', defaults.arrow, 0)}\n")
+    for index in sorted(defaults.palettes):
+        item = PaletteDef(index, defaults.palettes[index])
+        lines.append(format_palette(item.index, item.rgb))
+    if defaults.color is not None:
+        color = _as_int("color", defaults.color, 0)
+        last: Optional[int] = None
+        if defaults.palettes:
+            last = _as_int("palette", sorted(defaults.palettes)[-1], 0)
+        # 直前の @ n r g b がすでにこの色を選んでいれば、繰り返し出力しない。
+        if last != color:
+            lines.append(f"@ {color}\n")
+    for svg in defaults.svgs:
+        lines.append(_svg_text(svg))
+    lines.append("\n")
+    return "".join(lines)
+
+
+def _plain_int(name: str, value: object) -> int:
+    if isinstance(value, bool):
+        raise TypeError(f"{name} は整数で指定してください")
+    try:
+        return operator.index(value)  # type: ignore[arg-type]
+    except TypeError:
+        raise TypeError(f"{name} は整数で指定してください") from None
+
+
+def _int_between(name: str, value: object, lo: int, hi: int) -> int:
+    number = _plain_int(name, value)
+    if not lo <= number <= hi:
+        raise ValueError(f"{name} は {lo}..{hi} の範囲です: {number}")
+    return number
+
+
+def _as_float(name: str, value: object) -> float:
+    if isinstance(value, bool):
+        raise TypeError(f"{name} は数値で指定してください")
+    try:
+        return float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        raise TypeError(f"{name} は数値で指定してください") from None
+
+
+def _float_token(value: float) -> str:
+    if value == int(value) and abs(value) < 1e15:
+        return str(int(value))
+    return format(value, ".6g")
+
+
+def _rotation(value: object) -> str:
+    try:
+        numbers = tuple(_as_float("rotation", item) for item in value)  # type: ignore[union-attr]
+    except TypeError:
+        raise TypeError("rotation は 1〜3 個の数値にしてください") from None
+    if not 1 <= len(numbers) <= 3:
+        raise ValueError(f"rotation は 1〜3 個の数値にしてください（{len(numbers)} 個渡されました）")
+    return " ".join(_float_token(number) for number in numbers)
+
+
+def _layers(name: str, values: object) -> str:
+    try:
+        numbers = [_as_int(name, item, 1) for item in values]  # type: ignore[union-attr]
+    except TypeError:
+        raise TypeError(f"{name} はレイヤ番号の列にしてください") from None
+    return " ".join(str(number) for number in numbers)