omnichar-sdk 0.0.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- omnichar_sdk/__init__.py +71 -0
- omnichar_sdk/character.py +429 -0
- omnichar_sdk/charfile.py +343 -0
- omnichar_sdk/cli.py +190 -0
- omnichar_sdk/limits.py +34 -0
- omnichar_sdk/lora.py +229 -0
- omnichar_sdk/prompt.py +91 -0
- omnichar_sdk/py.typed +0 -0
- omnichar_sdk/references.py +146 -0
- omnichar_sdk/sheet.py +108 -0
- omnichar_sdk-0.0.1.dist-info/METADATA +91 -0
- omnichar_sdk-0.0.1.dist-info/RECORD +15 -0
- omnichar_sdk-0.0.1.dist-info/WHEEL +4 -0
- omnichar_sdk-0.0.1.dist-info/entry_points.txt +2 -0
- omnichar_sdk-0.0.1.dist-info/licenses/LICENSE +201 -0
omnichar_sdk/__init__.py
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Read Omnichar Studio ``.char`` character files; images need the ``images`` extra."""
|
|
3
|
+
|
|
4
|
+
from .character import Character, CharacterInfo
|
|
5
|
+
from .charfile import (
|
|
6
|
+
FORMAT_VERSION,
|
|
7
|
+
MAGIC,
|
|
8
|
+
ORIGIN_HARVESTED,
|
|
9
|
+
ORIGIN_ORIGINAL,
|
|
10
|
+
ROLE_BODY,
|
|
11
|
+
ROLE_CLOTH,
|
|
12
|
+
ROLE_FACE,
|
|
13
|
+
ROLES,
|
|
14
|
+
CharChanged,
|
|
15
|
+
CharDoc,
|
|
16
|
+
CharError,
|
|
17
|
+
Manifest,
|
|
18
|
+
looks_like_char,
|
|
19
|
+
payload_key,
|
|
20
|
+
read,
|
|
21
|
+
)
|
|
22
|
+
from .lora import (
|
|
23
|
+
KEY_SUFFIXES,
|
|
24
|
+
KEY_WRAPPERS,
|
|
25
|
+
Lora,
|
|
26
|
+
Portability,
|
|
27
|
+
module_stem,
|
|
28
|
+
safe_output_name,
|
|
29
|
+
)
|
|
30
|
+
from .prompt import STYLES, prompt_prefix
|
|
31
|
+
from .references import FIT_MODES, SIZE_POLICIES, Reference, allocate_roles, common_size, fit_roles
|
|
32
|
+
from .sheet import reference_sheet, sheet_png
|
|
33
|
+
|
|
34
|
+
__version__ = "0.0.1"
|
|
35
|
+
|
|
36
|
+
__all__ = [
|
|
37
|
+
"FIT_MODES",
|
|
38
|
+
"KEY_SUFFIXES",
|
|
39
|
+
"KEY_WRAPPERS",
|
|
40
|
+
"FORMAT_VERSION",
|
|
41
|
+
"MAGIC",
|
|
42
|
+
"ORIGIN_HARVESTED",
|
|
43
|
+
"ORIGIN_ORIGINAL",
|
|
44
|
+
"ROLES",
|
|
45
|
+
"ROLE_BODY",
|
|
46
|
+
"ROLE_CLOTH",
|
|
47
|
+
"ROLE_FACE",
|
|
48
|
+
"SIZE_POLICIES",
|
|
49
|
+
"STYLES",
|
|
50
|
+
"CharChanged",
|
|
51
|
+
"CharDoc",
|
|
52
|
+
"CharError",
|
|
53
|
+
"Character",
|
|
54
|
+
"CharacterInfo",
|
|
55
|
+
"Lora",
|
|
56
|
+
"Manifest",
|
|
57
|
+
"Portability",
|
|
58
|
+
"Reference",
|
|
59
|
+
"__version__",
|
|
60
|
+
"allocate_roles",
|
|
61
|
+
"common_size",
|
|
62
|
+
"fit_roles",
|
|
63
|
+
"looks_like_char",
|
|
64
|
+
"module_stem",
|
|
65
|
+
"payload_key",
|
|
66
|
+
"prompt_prefix",
|
|
67
|
+
"reference_sheet",
|
|
68
|
+
"sheet_png",
|
|
69
|
+
"read",
|
|
70
|
+
"safe_output_name",
|
|
71
|
+
]
|
|
@@ -0,0 +1,429 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""``Character``: one ``.char``, read a member at a time so a held handle cannot go stale."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import io
|
|
7
|
+
import struct
|
|
8
|
+
import zipfile
|
|
9
|
+
from collections.abc import Generator, Sequence
|
|
10
|
+
from contextlib import contextmanager
|
|
11
|
+
from dataclasses import dataclass
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from typing import TYPE_CHECKING, Any
|
|
14
|
+
|
|
15
|
+
from . import charfile as cf
|
|
16
|
+
from . import limits
|
|
17
|
+
from .lora import Lora, measure_portability, read_safetensors_header_stream
|
|
18
|
+
from .prompt import prompt_prefix
|
|
19
|
+
from .references import Reference, fit_roles
|
|
20
|
+
from .sheet import reference_sheet, sheet_png
|
|
21
|
+
|
|
22
|
+
if TYPE_CHECKING: # pragma: no cover
|
|
23
|
+
from PIL.Image import Image
|
|
24
|
+
|
|
25
|
+
#: PNG signature plus the IHDR chunk: width and height are at a fixed offset in the first 24 bytes.
|
|
26
|
+
_PNG_HEADER_BYTES = 24
|
|
27
|
+
_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@dataclass(frozen=True)
|
|
31
|
+
class CharacterInfo:
|
|
32
|
+
"""Everything about a character that costs nothing to read."""
|
|
33
|
+
|
|
34
|
+
name: str
|
|
35
|
+
char_id: str
|
|
36
|
+
description: str
|
|
37
|
+
hints: list[str]
|
|
38
|
+
ref_count: int
|
|
39
|
+
ref_archs: list[str]
|
|
40
|
+
lora_archs: list[str]
|
|
41
|
+
format_version: int
|
|
42
|
+
created_at: int
|
|
43
|
+
modified_at: int
|
|
44
|
+
size_bytes: int
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@contextmanager
|
|
48
|
+
def _memory_archive(data: bytes, label: str) -> Generator[zipfile.ZipFile]:
|
|
49
|
+
"""A zip held in memory, raising the same error a file on disk would."""
|
|
50
|
+
try:
|
|
51
|
+
archive = zipfile.ZipFile(io.BytesIO(data), "r")
|
|
52
|
+
except zipfile.BadZipFile as error:
|
|
53
|
+
raise cf.CharError(
|
|
54
|
+
f"{label} is not a readable character file. It may have been truncated in "
|
|
55
|
+
"transfer; download it again."
|
|
56
|
+
) from error
|
|
57
|
+
try:
|
|
58
|
+
yield archive
|
|
59
|
+
finally:
|
|
60
|
+
archive.close()
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _png_size(data: bytes) -> tuple[int, int]:
|
|
64
|
+
"""Width and height from a PNG's IHDR, or zeroes when the bytes are not a PNG."""
|
|
65
|
+
if len(data) < _PNG_HEADER_BYTES or not data.startswith(_PNG_SIGNATURE):
|
|
66
|
+
return (0, 0)
|
|
67
|
+
width, height = struct.unpack(">II", data[16:24])
|
|
68
|
+
return (int(width), int(height))
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class Character:
|
|
72
|
+
"""A ``.char`` on disk or in memory. Construct with `open`, `from_bytes` or `from_file`."""
|
|
73
|
+
|
|
74
|
+
def __init__(
|
|
75
|
+
self,
|
|
76
|
+
manifest: cf.Manifest,
|
|
77
|
+
*,
|
|
78
|
+
path: Path | None = None,
|
|
79
|
+
data: bytes | None = None,
|
|
80
|
+
label: str = "",
|
|
81
|
+
manifest_sha: str = "",
|
|
82
|
+
stamp: tuple[int, int] | None = None,
|
|
83
|
+
size_bytes: int = 0,
|
|
84
|
+
) -> None:
|
|
85
|
+
self._manifest = manifest
|
|
86
|
+
self._path = path
|
|
87
|
+
self._data = data
|
|
88
|
+
self._label = label
|
|
89
|
+
self._manifest_sha = manifest_sha
|
|
90
|
+
self._stamp = stamp
|
|
91
|
+
self._size_bytes = size_bytes
|
|
92
|
+
|
|
93
|
+
# --- construction -----------------------------------------------------------------------
|
|
94
|
+
|
|
95
|
+
@classmethod
|
|
96
|
+
def open(cls, path: Path | str) -> Character:
|
|
97
|
+
"""Open a ``.char``, validating only its manifest."""
|
|
98
|
+
target = Path(path)
|
|
99
|
+
with cf.open_archive(target) as archive:
|
|
100
|
+
raw = cf.read_manifest_bytes(archive, target.name)
|
|
101
|
+
manifest = cf.parse_manifest(raw, target.name)
|
|
102
|
+
stat = target.stat()
|
|
103
|
+
return cls(
|
|
104
|
+
manifest,
|
|
105
|
+
path=target,
|
|
106
|
+
label=target.name,
|
|
107
|
+
manifest_sha=cf.sha256_bytes(raw),
|
|
108
|
+
stamp=(stat.st_mtime_ns, stat.st_size),
|
|
109
|
+
size_bytes=stat.st_size,
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
@classmethod
|
|
113
|
+
def from_bytes(cls, data: bytes, label: str = "character") -> Character:
|
|
114
|
+
"""Open a ``.char`` already in memory, where nothing can change under it."""
|
|
115
|
+
with _memory_archive(data, label) as archive:
|
|
116
|
+
cf.check_archive(archive, label)
|
|
117
|
+
raw = cf.read_manifest_bytes(archive, label)
|
|
118
|
+
manifest = cf.parse_manifest(raw, label)
|
|
119
|
+
return cls(
|
|
120
|
+
manifest,
|
|
121
|
+
data=data,
|
|
122
|
+
label=label,
|
|
123
|
+
manifest_sha=cf.sha256_bytes(raw),
|
|
124
|
+
size_bytes=len(data),
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
@classmethod
|
|
128
|
+
def from_file(cls, stream: Any, label: str = "character") -> Character:
|
|
129
|
+
"""Read a ``.char`` from a stream, bounded so an endless one cannot exhaust memory."""
|
|
130
|
+
cap = limits.MAX_TOTAL_UNCOMPRESSED_BYTES
|
|
131
|
+
data = stream.read(cap + 1)
|
|
132
|
+
if len(data) > cap:
|
|
133
|
+
raise cf.CharError(
|
|
134
|
+
f"{label} is larger than {cap} bytes, which no character reaches. "
|
|
135
|
+
"Do not open it; get the character from a source you trust."
|
|
136
|
+
)
|
|
137
|
+
return cls.from_bytes(data, label)
|
|
138
|
+
|
|
139
|
+
# --- identity ---------------------------------------------------------------------------
|
|
140
|
+
|
|
141
|
+
@property
|
|
142
|
+
def manifest(self) -> cf.Manifest:
|
|
143
|
+
return self._manifest
|
|
144
|
+
|
|
145
|
+
@property
|
|
146
|
+
def name(self) -> str:
|
|
147
|
+
return self._manifest.name or Path(self._label).stem
|
|
148
|
+
|
|
149
|
+
@property
|
|
150
|
+
def char_id(self) -> str:
|
|
151
|
+
return self._manifest.char_id
|
|
152
|
+
|
|
153
|
+
@property
|
|
154
|
+
def format_version(self) -> int:
|
|
155
|
+
"""What the file declared, not what this build reads."""
|
|
156
|
+
return self._manifest.format_version
|
|
157
|
+
|
|
158
|
+
@property
|
|
159
|
+
def created_at(self) -> int:
|
|
160
|
+
return self._manifest.created_at
|
|
161
|
+
|
|
162
|
+
@property
|
|
163
|
+
def modified_at(self) -> int:
|
|
164
|
+
return self._manifest.modified_at
|
|
165
|
+
|
|
166
|
+
# --- member access ----------------------------------------------------------------------
|
|
167
|
+
|
|
168
|
+
@contextmanager
|
|
169
|
+
def _archive(self) -> Generator[zipfile.ZipFile]:
|
|
170
|
+
"""An open archive, proven to still be the file this character was built from."""
|
|
171
|
+
if self._data is not None:
|
|
172
|
+
with _memory_archive(self._data, self._label) as archive:
|
|
173
|
+
yield archive
|
|
174
|
+
return
|
|
175
|
+
assert self._path is not None
|
|
176
|
+
stat = self._path.stat()
|
|
177
|
+
current = (stat.st_mtime_ns, stat.st_size)
|
|
178
|
+
with cf.open_archive(self._path) as archive:
|
|
179
|
+
if current != self._stamp:
|
|
180
|
+
raw = cf.read_manifest_bytes(archive, self._label)
|
|
181
|
+
if cf.sha256_bytes(raw) != self._manifest_sha:
|
|
182
|
+
raise cf.CharChanged(
|
|
183
|
+
f"{self._label} was replaced while it was open. Open it again to read "
|
|
184
|
+
"the new version."
|
|
185
|
+
)
|
|
186
|
+
self._stamp = current
|
|
187
|
+
yield archive
|
|
188
|
+
|
|
189
|
+
def _read(self, member: str) -> bytes:
|
|
190
|
+
"""One member's bytes, refusing a nested archive."""
|
|
191
|
+
if not member:
|
|
192
|
+
raise cf.CharError(
|
|
193
|
+
f"{self._label} lists a file with no path in its manifest, so it cannot be read. "
|
|
194
|
+
"Export the character again from Omnichar Studio."
|
|
195
|
+
)
|
|
196
|
+
with self._archive() as archive:
|
|
197
|
+
try:
|
|
198
|
+
data = archive.read(member)
|
|
199
|
+
except KeyError:
|
|
200
|
+
raise self._missing(member) from None
|
|
201
|
+
return cf.check_member(member, data, self._label)
|
|
202
|
+
|
|
203
|
+
def _missing(self, member: str) -> cf.CharError:
|
|
204
|
+
return cf.CharError(
|
|
205
|
+
f"{self._label} has no {member!r}, which its manifest lists. The character is "
|
|
206
|
+
"incomplete; export it again from Omnichar Studio."
|
|
207
|
+
)
|
|
208
|
+
|
|
209
|
+
def _prefix(self, archive: zipfile.ZipFile, member: str, count: int) -> bytes:
|
|
210
|
+
"""The first ``count`` bytes of a member, checked and decompressed no further than that."""
|
|
211
|
+
try:
|
|
212
|
+
with archive.open(member, "r") as stream:
|
|
213
|
+
data = stream.read(count)
|
|
214
|
+
except KeyError:
|
|
215
|
+
raise self._missing(member) from None
|
|
216
|
+
return cf.check_member(member, data, self._label)
|
|
217
|
+
|
|
218
|
+
# --- the facade -------------------------------------------------------------------------
|
|
219
|
+
|
|
220
|
+
def get_description(self) -> str:
|
|
221
|
+
"""The locked character description, or an empty string when the file carries none."""
|
|
222
|
+
member = str(self._manifest.text.get("path") or "")
|
|
223
|
+
if not member:
|
|
224
|
+
return ""
|
|
225
|
+
return self._read(member).decode("utf-8", errors="replace")
|
|
226
|
+
|
|
227
|
+
def get_hints(self) -> list[str]:
|
|
228
|
+
return [str(hint) for hint in self._manifest.hints]
|
|
229
|
+
|
|
230
|
+
def get_ref_archs(self) -> list[str]:
|
|
231
|
+
"""Architectures with a compiled reference set."""
|
|
232
|
+
return sorted(k for k in self._manifest.payloads if not k.endswith(f"-{cf.PAYLOAD_LORA}"))
|
|
233
|
+
|
|
234
|
+
def get_lora_archs(self) -> list[str]:
|
|
235
|
+
"""Architectures with a trained adapter."""
|
|
236
|
+
suffix = f"-{cf.PAYLOAD_LORA}"
|
|
237
|
+
return sorted(k[: -len(suffix)] for k in self._manifest.payloads if k.endswith(suffix))
|
|
238
|
+
|
|
239
|
+
def get_info(self) -> CharacterInfo:
|
|
240
|
+
return CharacterInfo(
|
|
241
|
+
name=self.name,
|
|
242
|
+
char_id=self.char_id,
|
|
243
|
+
description=self.get_description(),
|
|
244
|
+
hints=self.get_hints(),
|
|
245
|
+
ref_count=len(self._manifest.refs),
|
|
246
|
+
ref_archs=self.get_ref_archs(),
|
|
247
|
+
lora_archs=self.get_lora_archs(),
|
|
248
|
+
format_version=self.format_version,
|
|
249
|
+
created_at=self.created_at,
|
|
250
|
+
modified_at=self.modified_at,
|
|
251
|
+
size_bytes=self._size_bytes,
|
|
252
|
+
)
|
|
253
|
+
|
|
254
|
+
def get_references(
|
|
255
|
+
self,
|
|
256
|
+
arch: str | None = None,
|
|
257
|
+
role: str | None = None,
|
|
258
|
+
origin: str | None = None,
|
|
259
|
+
limit: int | None = None,
|
|
260
|
+
) -> list[Reference]:
|
|
261
|
+
"""References in manifest order, which is what a prompt's positions refer to."""
|
|
262
|
+
if arch is not None and origin is not None:
|
|
263
|
+
raise ValueError(
|
|
264
|
+
"get_references takes arch or origin, not both. A compiled payload records no "
|
|
265
|
+
f"per-reference origin, so origin={origin!r} cannot be applied to arch={arch!r}. "
|
|
266
|
+
"Drop origin, or drop arch to read the original references."
|
|
267
|
+
)
|
|
268
|
+
if arch is None:
|
|
269
|
+
entries = list(self._manifest.refs)
|
|
270
|
+
else:
|
|
271
|
+
payload = self._manifest.payloads.get(arch)
|
|
272
|
+
if not isinstance(payload, dict):
|
|
273
|
+
raise cf.CharError(
|
|
274
|
+
f"{self.name} has no compiled references for {arch}. It has "
|
|
275
|
+
f"{', '.join(self.get_ref_archs()) or 'none'}."
|
|
276
|
+
)
|
|
277
|
+
entries = list(payload.get("files") or [])
|
|
278
|
+
|
|
279
|
+
refs = self._build_references(entries)
|
|
280
|
+
if origin is not None:
|
|
281
|
+
refs = [ref for ref in refs if ref.origin == origin]
|
|
282
|
+
if role is not None:
|
|
283
|
+
refs = [ref for ref in refs if ref.role == role]
|
|
284
|
+
if limit is not None:
|
|
285
|
+
refs = fit_roles(refs, limit)
|
|
286
|
+
return refs
|
|
287
|
+
|
|
288
|
+
def _build_references(self, entries: Sequence[dict[str, Any]]) -> list[Reference]:
|
|
289
|
+
"""Reference objects, reading a PNG header only for entries that record no size."""
|
|
290
|
+
missing = [
|
|
291
|
+
str(e.get("path") or "")
|
|
292
|
+
for e in entries
|
|
293
|
+
if not (int(e.get("width") or 0) and int(e.get("height") or 0))
|
|
294
|
+
]
|
|
295
|
+
sizes: dict[str, tuple[int, int]] = {}
|
|
296
|
+
if missing:
|
|
297
|
+
with self._archive() as archive:
|
|
298
|
+
for member in missing:
|
|
299
|
+
if not member:
|
|
300
|
+
continue
|
|
301
|
+
sizes[member] = _png_size(
|
|
302
|
+
self._prefix(archive, member, _PNG_HEADER_BYTES)
|
|
303
|
+
)
|
|
304
|
+
out: list[Reference] = []
|
|
305
|
+
for entry in entries:
|
|
306
|
+
path = str(entry.get("path") or "")
|
|
307
|
+
width = int(entry.get("width") or 0)
|
|
308
|
+
height = int(entry.get("height") or 0)
|
|
309
|
+
if not (width and height):
|
|
310
|
+
width, height = sizes.get(path, (0, 0))
|
|
311
|
+
out.append(
|
|
312
|
+
Reference(
|
|
313
|
+
path=path,
|
|
314
|
+
role=cf.role_of(entry),
|
|
315
|
+
origin=cf.origin_of(entry),
|
|
316
|
+
width=width,
|
|
317
|
+
height=height,
|
|
318
|
+
sha256=str(entry.get("sha256") or ""),
|
|
319
|
+
_read=self._read,
|
|
320
|
+
)
|
|
321
|
+
)
|
|
322
|
+
return out
|
|
323
|
+
|
|
324
|
+
def get_lora(self, arch: str | None = None) -> Lora | None:
|
|
325
|
+
"""The adapter for ``arch``; with several and no ``arch`` it raises rather than guess."""
|
|
326
|
+
available = self.get_lora_archs()
|
|
327
|
+
if not available:
|
|
328
|
+
return None
|
|
329
|
+
if arch is None:
|
|
330
|
+
if len(available) > 1:
|
|
331
|
+
raise cf.CharError(
|
|
332
|
+
f"{self.name} carries adapters for {', '.join(available)}. "
|
|
333
|
+
"Name one with get_lora(arch=...)."
|
|
334
|
+
)
|
|
335
|
+
arch = available[0]
|
|
336
|
+
key = cf.payload_key(arch, cf.PAYLOAD_LORA)
|
|
337
|
+
entry = self._manifest.payloads.get(key)
|
|
338
|
+
if not isinstance(entry, dict):
|
|
339
|
+
return None
|
|
340
|
+
files = [str(f.get("path")) for f in entry.get("files") or [] if f.get("path")]
|
|
341
|
+
if not files:
|
|
342
|
+
return None
|
|
343
|
+
member = files[0]
|
|
344
|
+
raw_training = entry.get("training")
|
|
345
|
+
training: dict[str, Any] = raw_training if isinstance(raw_training, dict) else {}
|
|
346
|
+
filename = Path(member).name
|
|
347
|
+
keys = self._adapter_keys(member, filename)
|
|
348
|
+
verdict, reason = measure_portability(arch, keys)
|
|
349
|
+
return Lora(
|
|
350
|
+
arch=arch,
|
|
351
|
+
base=str(entry.get("base") or ""),
|
|
352
|
+
rank=int(training.get("rank") or 0),
|
|
353
|
+
steps=int(training.get("steps") or 0),
|
|
354
|
+
resolution=int(training.get("resolution") or 0),
|
|
355
|
+
strength=float(entry.get("strength") or 1.0),
|
|
356
|
+
filename=filename,
|
|
357
|
+
portability=verdict,
|
|
358
|
+
reason=reason,
|
|
359
|
+
_read=self._read,
|
|
360
|
+
_read_header=lambda: self._adapter_header(member, filename),
|
|
361
|
+
_member=member,
|
|
362
|
+
)
|
|
363
|
+
|
|
364
|
+
def _adapter_keys(self, member: str, label: str) -> list[str]:
|
|
365
|
+
"""Tensor names from the adapter's header."""
|
|
366
|
+
return [k for k in self._adapter_header(member, label) if k != "__metadata__"]
|
|
367
|
+
|
|
368
|
+
def _adapter_header(self, member: str, label: str) -> dict[str, Any]:
|
|
369
|
+
"""The adapter's header, decompressing no more of the member than the header itself."""
|
|
370
|
+
with self._archive() as archive:
|
|
371
|
+
# The nested-archive guard, before the header is streamed out of the member.
|
|
372
|
+
self._prefix(archive, member, len(limits.ZIP_MAGIC))
|
|
373
|
+
try:
|
|
374
|
+
with archive.open(member, "r") as stream:
|
|
375
|
+
header = read_safetensors_header_stream(stream, label)
|
|
376
|
+
except KeyError:
|
|
377
|
+
raise self._missing(member) from None
|
|
378
|
+
return header
|
|
379
|
+
|
|
380
|
+
def reference_sheet(
|
|
381
|
+
self,
|
|
382
|
+
arch: str | None = None,
|
|
383
|
+
role: str | None = None,
|
|
384
|
+
limit: int | None = None,
|
|
385
|
+
origin: str | None = None,
|
|
386
|
+
*,
|
|
387
|
+
first_position: int = 1,
|
|
388
|
+
**options: Any,
|
|
389
|
+
) -> Image:
|
|
390
|
+
"""References as one contact sheet, numbered from ``first_position`` as a prompt is."""
|
|
391
|
+
refs = self.get_references(arch=arch, role=role, origin=origin, limit=limit)
|
|
392
|
+
options.setdefault("title", self.name)
|
|
393
|
+
options.setdefault("subtitle", f"{len(refs)} references" + (f" · {arch}" if arch else ""))
|
|
394
|
+
return reference_sheet(refs, first_position=first_position, **options)
|
|
395
|
+
|
|
396
|
+
def reference_sheet_png(self, *args: Any, **options: Any) -> bytes:
|
|
397
|
+
"""The contact sheet as PNG bytes."""
|
|
398
|
+
return sheet_png(self.reference_sheet(*args, **options))
|
|
399
|
+
|
|
400
|
+
def save_reference_sheet(self, path: Path | str, *args: Any, **options: Any) -> Path:
|
|
401
|
+
"""Write the contact sheet to ``path`` as a PNG, adding the extension when it has none."""
|
|
402
|
+
target = Path(path)
|
|
403
|
+
if target.suffix.lower() != ".png":
|
|
404
|
+
target = target.with_suffix(".png")
|
|
405
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
406
|
+
target.write_bytes(self.reference_sheet_png(*args, **options))
|
|
407
|
+
return target
|
|
408
|
+
|
|
409
|
+
def get_prompt(
|
|
410
|
+
self,
|
|
411
|
+
style: str = "ordinal",
|
|
412
|
+
first_position: int = 1,
|
|
413
|
+
role_lines: bool = False,
|
|
414
|
+
count: int | None = None,
|
|
415
|
+
arch: str | None = None,
|
|
416
|
+
) -> str:
|
|
417
|
+
"""Prompt text naming the positions this character's references will occupy."""
|
|
418
|
+
refs = self.get_references(arch=arch, limit=count)
|
|
419
|
+
return prompt_prefix(
|
|
420
|
+
self.name,
|
|
421
|
+
self.get_description(),
|
|
422
|
+
[ref.role for ref in refs],
|
|
423
|
+
first_position=first_position,
|
|
424
|
+
style=style,
|
|
425
|
+
role_lines=role_lines,
|
|
426
|
+
)
|
|
427
|
+
|
|
428
|
+
def __repr__(self) -> str:
|
|
429
|
+
return f"<Character {self.name!r} refs={len(self._manifest.refs)}>"
|