s3dgraphy 1.6.0.dev83__tar.gz → 1.6.0.dev85__tar.gz

{s3dgraphy-1.6.0.dev83/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev85}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev83
+Version: 1.6.0.dev85
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>

{s3dgraphy-1.6.0.dev83 → s3dgraphy-1.6.0.dev85}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev83"
+version = "1.6.0.dev85"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"

{s3dgraphy-1.6.0.dev83 → s3dgraphy-1.6.0.dev85}/src/s3dgraphy/JSON_config/em_state_symbols.json

@@ -82,6 +82,18 @@
         "en": "A file is here but its bytes are zeros: an incomplete copy, to be made again."
       }
     },
+    "file.in_cloud": {
+      "family": "file",
+      "glyph": "⤓",
+      "label": {
+        "it": "nel cloud",
+        "en": "in the cloud"
+      },
+      "meaning": {
+        "it": "Il file è qui come segnaposto: i suoi byte sono nel cloud (OneDrive, iCloud, Dropbox «solo online»). Non si legge finché non lo scarichi.",
+        "en": "The file is here as a placeholder: its bytes are in the cloud (OneDrive, iCloud, Dropbox «online only»). It is not read until you download it."
+      }
+    },
     "node.reachable": {
       "family": "node",
       "glyph": "⬢",

{s3dgraphy-1.6.0.dev83 → s3dgraphy-1.6.0.dev85}/src/s3dgraphy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.6.0.dev83"
+__version__ = "1.6.0.dev85"
 __datamodel_version__ = "1.5.5"  # s3Dgraphy connections datamodel version
 
 # s3Dgraphy/__init__.py

{s3dgraphy-1.6.0.dev83 → s3dgraphy-1.6.0.dev85}/src/s3dgraphy/api.py

@@ -3246,9 +3246,11 @@ def resolve_files(graph: Graph, *, project_root: Optional[str] = None,
                   base_dirs: Sequence[str] = (), cache_dirs: Sequence[str] = (),
                   on_node: Optional[Callable[[str], bool]] = None,
                   hasher: Optional[Callable[[str], str]] = None,
-                  verify: bool = False) -> List[Dict[str, Any]]:
+                  verify: bool = False,
+                  cloud: Optional[Callable[[str], bool]] = None) -> List[Dict[str, Any]]:
     """The STATE of every resource of ``graph`` — ``on_disk``, ``on_node``,
-    ``both``, ``reference_only``, ``missing``, ``empty_copy`` — trying cache →
+    ``both``, ``reference_only``, ``missing``, ``empty_copy``, ``in_cloud``
+    (``cloud(path)``: bytes only in a cloud, never read) — trying cache →
     known paths (the EM standard tree of ``project_root`` first) → node
     (``on_node(hex)``) → reference. The one resolver every tool calls.
     ``verify`` (with a ``hasher``): a file here whose bytes are not the
@@ -3256,7 +3258,8 @@ def resolve_files(graph: Graph, *, project_root: Optional[str] = None,
     :mod:`s3dgraphy.resources.locate`."""
     from .resources.locate import resolve_graph
     return resolve_graph(graph, project_root=project_root, base_dirs=base_dirs,
-                         cache_dirs=cache_dirs, on_node=on_node, hasher=hasher, verify=verify)
+                         cache_dirs=cache_dirs, on_node=on_node, hasher=hasher, verify=verify,
+                         cloud=cloud)
 
 
 def resolve_file(entry: Dict[str, Any], **kwargs) -> Dict[str, Any]:

{s3dgraphy-1.6.0.dev83 → s3dgraphy-1.6.0.dev85}/src/s3dgraphy/resources/asset_list.py

@@ -65,6 +65,12 @@ TOOLS = ("decimate_bake", "gltfpack", "ktx2", "tileset", "instance", "keep")
 #: The states of an asset for a target.
 STATES = ("ok", "todo", "missing", "na")
 
+#: What a tileset's row says in the place of its level (MICRO-ARCHIVE-ASSET-3).
+TILESET_SAY = "tileset · in streaming"
+
+#: The targets a tileset streams to (the archive keeps its master).
+STREAMED = ("mobile", "web", "desk")
+
 #: A file this many triangles or more is a tileset's job, not a decimation's.
 TILESET_FROM = 2_000_000
 
@@ -124,19 +130,30 @@ def _texture_rows(raw: Optional[Dict[str, Any]]) -> List[Dict[str, Any]]:
     return out
 
 
+def geometry_keys(raw: Optional[Dict[str, Any]]) -> List[str]:
+    """The ``geometry_key`` of each mesh of a measured file
+    (:func:`~.use_profiles.measure_gltf`), sorted, each once: two files with
+    the same keys hold the same geometry (the same topology and UVs), placed
+    anywhere. Empty when the file was not measured."""
+    if not raw or not isinstance(raw, dict):
+        return []
+    return sorted({str(o.get("geometry_key")) for o in raw.get("objects") or []
+                   if isinstance(o, dict) and o.get("geometry_key") and int(o.get("triangles") or 0) > 0})
+
+
 def _state_of(graph, entry: Dict[str, Any], states: Dict[str, str]) -> str:
     ids = [entry.get("id")] + [f["id"] for f in C._files(graph, entry) if f.get("id") != entry.get("id")]
     known = [states[i] for i in ids if i in states]
     if not known:
         return ""
-    for worst in ("missing", "empty_copy", "reference_only"):
+    for worst in ("missing", "empty_copy", "reference_only", "in_cloud"):
         if worst in known:
             return worst
     return known[0]
 
 
 def _version(graph, entry: Dict[str, Any], summary: Dict[str, Any], *, states, measure,
-             changed) -> Dict[str, Any]:
+             changed, tiles=None) -> Dict[str, Any]:
     from .graph_compose import level_say, made_by, made_by_say
     raw = None
     if measure is not None and not summary.get("tileset"):
@@ -147,10 +164,20 @@ def _version(graph, entry: Dict[str, Any], summary: Dict[str, Any], *, states, m
     made = made_by(graph, entry["id"])
     ids = [entry["id"]] + [f["id"] for f in C._files(graph, entry) if f.get("id") != entry["id"]]
     now = next((changed[i] for i in ids if changed and i in changed), "")
+    state = _state_of(graph, entry, states)
+    # MICRO-ARCHIVE-ASSET-3 · a tileset's tiles, each by its head (the caller
+    # reads them: ``tiles(entry)``); its row says «tileset · in streaming»
+    tstats = None
+    if summary.get("tileset") and tiles is not None and state != "in_cloud":
+        try:
+            tstats = tiles(entry)
+        except Exception:  # noqa: BLE001 — unreadable: not known
+            tstats = None
     return {"id": entry["id"], "name": summary.get("name") or entry.get("name") or "",
             "asset_id": entry.get("asset_id"), "master": bool(entry.get("master")),
             "level": summary.get("level") or "", "lod_level": summary.get("lod_level") or "",
-            "level_say": level_say(entry), "use": list(entry.get("use") or []),
+            "level_say": TILESET_SAY if summary.get("tileset") else level_say(entry),
+            "use": list(entry.get("use") or []),
             "url": summary.get("url") or "", "checksum": summary.get("checksum") or "",
             "stamped": bool(summary.get("checksum")),
             "size_bytes": summary.get("size_bytes"), "triangles": summary.get("triangles"),
@@ -158,12 +185,22 @@ def _version(graph, entry: Dict[str, Any], summary: Dict[str, Any], *, states, m
             "texture_side": summary.get("texture_side"), "ktx2": summary.get("ktx2"),
             "tileset": bool(summary.get("tileset")),
             "textures": _texture_rows(raw),
+            # MICRO-ARCHIVE-ASSET-2 · the shape of the file: its meshes' geometry
+            # keys (indices and UVs, wherever placed — Draco/meshopt bytes when
+            # compressed) and its compression, for the forms repeated
+            "geometry_keys": geometry_keys(raw),
+            "compression": (raw.get("compression") or "") if isinstance(raw, dict) else "",
             "texture_count": len(raw.get("textures") or {}) if isinstance(raw, dict) else
             _data(_node(graph, entry["id"])).get("texture_count"),
-            "state": _state_of(graph, entry, states),
+            "state": state,
+            # MICRO-TESTATA-CLOUD · its bytes only in a cloud (not downloaded):
+            # never measured here, its numbers are the graph's estimate
+            "in_cloud": state == "in_cloud",
             "made": made, "made_say": made_by_say(made),
             "modified_after_stamp": bool(now) and not entry.get("master"), "sha256_now": now or "",
-            "loaded_by": []}
+            "loaded_by": [],
+            **({"tiles": {k: tstats.get(k) for k in ("tiles", "read", "max_triangles", "max_texture_side")},
+                "_tile_stats": tstats} if tstats else {})}
 
 
 # ── a target's state and proposal ───────────────────────────────────────────
@@ -288,6 +325,8 @@ def _targets(graph, row: Dict[str, Any], cand: Dict[str, Any], versions: List[Di
         st_a, why_a = "todo", "master senza sha256: timbralo"
     elif m["state"] in ("missing", "empty_copy", "reference_only"):
         st_a, why_a = "todo", f"il file del master non c'è ({m['state'].replace('_', ' ')})"
+    elif m["state"] == "in_cloud" and "tileset_master" not in codes:
+        st_a, why_a = "ok", "master timbrato, il file è nel cloud (non scaricato: non verificato)"
     elif "tileset_master" in codes:
         st_a, why_a = "todo", "dichiara il master del tileset (le mesh da cui viene)"
     elif not m["state"]:
@@ -296,21 +335,125 @@ def _targets(graph, row: Dict[str, Any], cand: Dict[str, Any], versions: List[Di
         st_a, why_a = "ok", "master timbrato e presente"
     out["arch"] = _target_cell("arch", state=st_a, loads=m["id"] if m else None, why=why_a,
                                source=src, kind=kind)
+
+    # MICRO-ARCHIVE-ASSET-3 · a tileset is «ok» for a target only if its
+    # tiles respect the target's band (per tile: triangles, texture side)
+    if tileset and lo:
+        from .tileset_fit import fit
+        tv = by.get(lo["id"]) or {}
+        for k in STREAMED:
+            f = fit(tv.get("_tile_stats"), bands(k))
+            if f["ok"]:
+                cell = _target_cell(k, state="ok", loads=lo["id"], why=f"in streaming: {f['why']}",
+                                    source=src, kind=kind)
+            elif f["known"]:
+                b = bands(k)
+                cell = _target_cell(k, state="todo", loads=lo["id"], why=f"le tile non rispettano la fascia: {f['why']}",
+                                    source=src, kind=kind)
+                cell["proposal"] = {"tool": "tileset", "triangles": b["object_triangles"],
+                                    "texture": b["object_texture_side"], "ktx2": k != "desk",
+                                    "why": (f"rifai le tile nella fascia ({b['object_triangles']:,} triangoli, "
+                                            f"{b['object_texture_side']} px per tile)").replace(",", ".")}
+            else:
+                cell = _target_cell(k, state="todo", loads=lo["id"], why=f["why"], source=src, kind=kind)
+                cell["proposal"] = {"tool": "keep", "triangles": None, "texture": None, "ktx2": False,
+                                    "why": "leggi le tile prima (il file del tileset su questo computer)"}
+            cell["tiles"] = {x: f[x] for x in ("ok", "known", "tiles", "read", "over_triangles", "over_texture",
+                                                "max_triangles", "max_texture_side")}
+            out[k] = cell
+    return out
+
+
+# ── MICRO-ARCHIVE-ASSET-3 · the tileset covers its meshes ───────────────────
+
+def _cited_alone(graph) -> Dict[str, str]:
+    """The nodes a narrative cites (an embed or a mention) → the narrative's
+    name: a mesh shown alone in a narrative is wanted one by one."""
+    try:
+        from ..narrative.query import citations
+        rows = citations(graph)
+    except Exception:  # noqa: BLE001 — no narrative layer: none cited
+        return {}
+    out: Dict[str, str] = {}
+    for r in rows:
+        out.setdefault(str(r.get("ref") or ""), str(r.get("narrative_name") or r.get("narrative_id") or ""))
     return out
 
 
+def cover_by_tilesets(graph, assets: List[Dict[str, Any]]) -> Dict[str, int]:
+    """A container whose tileset fits a target covers its meshes for it: each
+    says «coperta dal tileset di <contenitore>», has no proposal and is out
+    of the count (state ``na``, ``covered_by``). The exceptions, said and
+    left with their proposal: the container's meshes are of different epochs
+    («serve per epoca: il tileset non si divide»), or a mesh is cited alone in
+    a narrative. Where the tileset does not fit, the meshes keep their
+    proposal and say why the tileset does not cover them yet. → the meshes
+    covered per target."""
+    cited = None
+    n = {k: 0 for k in STREAMED}
+    for c in assets:
+        if c["kind"] != "container":
+            continue
+        tv = next((v for v in c["versions"] if v["tileset"] and v["id"] in
+                   {c["targets"][k]["loads"] for k in STREAMED}), None)
+        if tv is None:
+            continue
+        members = [a for a in assets if a is not c and a["kind"] == "rm"
+                   and any(x["id"] == c["id"] for x in a["containers"])]
+        if not members:
+            continue
+        if cited is None:
+            cited = _cited_alone(graph)
+        epochs = {tuple(sorted(a["epochs"])) for a in members}
+        by_epoch = len(epochs) > 1
+        for a in members:
+            alone = ("serve per epoca: il tileset non si divide" if by_epoch else
+                     f"usata da sola nella narrazione «{cited[a['id']]}»: il tileset non si divide"
+                     if a["id"] in cited else "")
+            for k in STREAMED:
+                tc, cell = c["targets"][k], a["targets"][k]
+                if cell["state"] == "na":
+                    continue
+                cell["tileset_of"] = {"id": c["id"], "name": c["name"], "state": tc["state"]}
+                if tc["state"] != "ok":
+                    cell["why"] = f"{cell['why']} (il tileset di {c['name']} non la copre: {tc['why']})"
+                    continue
+                if alone:
+                    cell["single"] = alone
+                    cell["why"] = f"{alone} — {cell['why']}"
+                    cell["proposal"] = {**cell["proposal"], "why": f"{alone} — {cell['proposal']['why']}"}
+                    continue
+                say = f"coperta dal tileset di {c['name']}"
+                for v in a["versions"]:
+                    if k in v["loaded_by"]:
+                        v["loaded_by"].remove(k)
+                a["targets"][k] = {"state": "na", "loads": cell["loads"], "why": say,
+                                   "covered_by": {"id": c["id"], "name": c["name"], "version": tv["id"]},
+                                   "tileset_of": cell["tileset_of"],
+                                   "proposal": {"tool": "keep", "triangles": None, "texture": None, "ktx2": False,
+                                                "why": say}}
+                n[k] += 1
+    return n
+
+
 # ── the list ─────────────────────────────────────────────────────────────────
 
 def asset_list(graph, *, states: Optional[Dict[str, str]] = None, measure=None,
                changed: Optional[Dict[str, str]] = None, in_room: bool = False,
-               models: Optional[Iterable[str]] = None, platform: str = "heriverse") -> Dict[str, Any]:
+               models: Optional[Iterable[str]] = None, platform: str = "heriverse",
+               tiles=None) -> Dict[str, Any]:
     """The assets of the study (``models``, default the published ones —
     representation models and the containers with a whole of their own),
     each with its versions (master first), their textures, its state and
     proposal per target (:data:`TARGETS`), the groups it belongs to
     (container, branch, epochs, family); the textures of the whole study once;
     the totals per target against the bands. → ``{targets, tools, assets,
-    textures, totals, counts, measured, estimated, say_it}``."""
+    textures, totals, counts, measured, estimated, say_it}``.
+
+    ``tiles(entry)`` (MICRO-ARCHIVE-ASSET-3, the caller's reader): a
+    tileset's tiles measured by their heads (:func:`.tileset_fit.measure_tiles`)
+    — the tileset is «ok» for a target only if they fit its band, and then it
+    covers its container's meshes (:func:`cover_by_tilesets`)."""
     from .alternatives import containers_of
     from .graph_compose import epochs_of
     states = dict(states or {})
@@ -327,7 +470,7 @@ def asset_list(graph, *, states: Optional[Dict[str, str]] = None, measure=None,
         versions = []
         for e in entries:
             s = C._summary(graph, e, measure)
-            v = _version(graph, e, s, states=states, measure=measure, changed=changed)
+            v = _version(graph, e, s, states=states, measure=measure, changed=changed, tiles=tiles)
             cache[e["id"]] = v
             versions.append(v)
             if not v["master"] and not v["tileset"]:
@@ -348,6 +491,7 @@ def asset_list(graph, *, states: Optional[Dict[str, str]] = None, measure=None,
         br = branch_of(master["url"] if master else (versions[0]["url"] if versions else ""))
         modified = [v["id"] for v in versions if v["modified_after_stamp"]]
         missing_files = [v["id"] for v in versions if v["state"] in ("missing", "empty_copy")]
+        cloud_files = [v["id"] for v in versions if v["state"] == "in_cloud"]
         a = {"id": row["id"], "name": row["name"], "kind": row["kind"],
              "description": str(getattr(node, "description", "") or ""),
              "containers": conts, "branch": br, "epochs": [x["name"] for x in epochs_of(graph, row["id"])],
@@ -356,7 +500,7 @@ def asset_list(graph, *, states: Optional[Dict[str, str]] = None, measure=None,
              "loaded_why": row.get("loaded_why") or "", "loaded_say": row.get("loaded_say") or "",
              "tileset_master": row.get("tileset_master"),
              "audit": {"versions": len(versions), "stamped": sum(1 for v in versions if v["stamped"]),
-                       "files_missing": missing_files, "unchecked": sum(1 for v in versions if not v["state"]),
+                       "files_missing": missing_files, "files_in_cloud": cloud_files, "unchecked": sum(1 for v in versions if not v["state"]),
                        "modified_after_stamp": modified,
                        "master_declared": (row.get("tileset_master") or {}).get("declared")}}
         assets.append(a)
@@ -370,6 +514,10 @@ def asset_list(graph, *, states: Optional[Dict[str, str]] = None, measure=None,
                                    "level": v["level"] or ("master" if v["master"] else "")})
                 if t["name"] not in ti["names"]:
                     ti["names"].append(t["name"])
+    covered = cover_by_tilesets(graph, assets)
+    for a in assets:
+        for v in a["versions"]:
+            v.pop("_tile_stats", None)
     textures = sorted(tex_index.values(), key=lambda t: (-len(t["uses"]), -t["gpu_bytes"], t["name"]))
     for t in textures:
         t["count"] = len(t["uses"])
@@ -380,6 +528,8 @@ def asset_list(graph, *, states: Optional[Dict[str, str]] = None, measure=None,
               "versions": sum(len(a["versions"]) for a in assets),
               "textures": len(textures), "shared_textures": sum(1 for t in textures if t["count"] > 1),
               "measured": n_meas, "estimated": n_est,
+              "in_cloud": sum(1 for a in assets for v in a["versions"] if v["in_cloud"]),
+              "covered_by_tileset": covered,
               "by_target": {k: {s: sum(1 for a in assets if a["targets"][k]["state"] == s) for s in STATES}
                             for k in TARGETS}}
     say = (f"{counts['assets']} asset ({counts['rms']} modelli, {counts['containers']} contenitori), "
@@ -387,6 +537,8 @@ def asset_list(graph, *, states: Optional[Dict[str, str]] = None, measure=None,
            f"({counts['shared_textures']} condivise)")
     say += (f"; {n_meas} versioni misurate dai file, {n_est} stimate dal grafo" if n_est
             else f"; {n_meas} versioni misurate dai file")
+    if counts["in_cloud"]:
+        say += f"; {counts['in_cloud']} nel cloud (non scaricate: stimate dal grafo)"
     return {"targets": {k: {**{x: v for x, v in TARGETS[k].items() if x != "uses"},
                             "uses": list(TARGETS[k]["uses"]), "bands": bands(k)} for k in TARGETS},
             "tools": list(TOOLS), "assets": assets, "textures": textures, "totals": totals,
@@ -406,6 +558,8 @@ def scene_totals(assets: Sequence[Dict[str, Any]], target: str) -> Dict[str, Any
     streamed = estimated = 0
     for a in assets:
         cell = a["targets"].get(target) or {}
+        if cell.get("covered_by"):
+            continue
         v = next((x for x in a["versions"] if x["id"] == cell.get("loads")), None)
         if v is None:
             continue

{s3dgraphy-1.6.0.dev83 → s3dgraphy-1.6.0.dev85}/src/s3dgraphy/resources/consolidate.py

@@ -357,7 +357,7 @@ def presence(graph, entry: Dict[str, Any], *, states: Optional[Dict[str, str]] =
     known = [states[i] for i in ids if i in states]
     state = known[0] if known else ""
     if len(known) > 1:
-        worst = next((s for s in ("missing", "empty_copy", "reference_only", "on_disk", "on_node")
+        worst = next((s for s in ("missing", "empty_copy", "reference_only", "in_cloud", "on_disk", "on_node")
                       if s in known), known[0])
         state = worst if not all(k == "both" for k in known) else "both"
     if not state:

{s3dgraphy-1.6.0.dev83 → s3dgraphy-1.6.0.dev85}/src/s3dgraphy/resources/locate.py

@@ -35,7 +35,7 @@ import re
 import urllib.parse
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
-STATES = ("on_disk", "on_node", "both", "reference_only", "missing", "empty_copy")
+STATES = ("on_disk", "on_node", "both", "reference_only", "missing", "empty_copy", "in_cloud")
 
 #: the order the positions are tried in
 ORDER = ("cache", "path", "node", "reference")
@@ -136,7 +136,8 @@ def resolve(entry: Dict[str, Any], *, project_root: Optional[str] = None,
             base_dirs: Iterable[str] = (), cache_dirs: Iterable[str] = (),
             on_node: Optional[Callable[[str], bool]] = None,
             hasher: Optional[Callable[[str], str]] = None,
-            verify: bool = False) -> Dict[str, Any]:
+            verify: bool = False,
+            cloud: Optional[Callable[[str], bool]] = None) -> Dict[str, Any]:
     """The state of ONE resource. ``entry`` is ``{id, locator, checksum}`` (what
     :func:`entries_of` gives for a graph). The project's standard tree is tried
     before ``base_dirs`` (C1). ``hasher(path) -> hex`` lets a file found on the
@@ -146,7 +147,16 @@ def resolve(entry: Dict[str, Any], *, project_root: Optional[str] = None,
     the file was modified after its stamp (MICRO-CONSOLIDA-2) — the state
     stays where the bytes are.
 
-    → ``{id, sha256, state, path, positions: [{kind, where, ok}], note}``."""
+    ``cloud(path) -> bool`` (MICRO-TESTATA-CLOUD): a file whose bytes are
+    only in a cloud (OneDrive, iCloud, Dropbox «online only»: the caller
+    asks the system, by metadata). Such a file is NEVER read here — not
+    hashed, not probed for zeros — since reading it would download it: it is
+    said ``in_cloud`` with its place in ``cloud_path``, and ``path`` stays
+    empty, so nothing downstream measures it by accident. Another candidate
+    that is here wins over it.
+
+    → ``{id, sha256, state, path, positions: [{kind, where, ok}], note,
+    cloud_path?}``."""
     from ..project_tree import search_bases
 
     rid = str(entry.get("id") or "")
@@ -158,10 +168,20 @@ def resolve(entry: Dict[str, Any], *, project_root: Optional[str] = None,
     bases = (search_bases(project_root) if project_root else []) + \
         [b for b in (base_dirs or ()) if b]
     positions: List[Dict[str, Any]] = []
-    path, empty = None, None
+    path, empty, cloud_at = None, None, None
+
+    def in_cloud(p: str) -> bool:
+        if cloud is None:
+            return False
+        try:
+            return bool(cloud(p))
+        except Exception:  # noqa: BLE001 — a system that cannot say: not in the cloud
+            return False
 
     # 1 · cache
     hit = in_cache(cache_dirs, hexd)
+    if hit and in_cloud(hit):
+        cloud_at, hit = hit, None
     positions.append({"kind": "cache", "where": hit or "", "ok": bool(hit)})
     if hit:
         path = hit
@@ -188,13 +208,17 @@ def resolve(entry: Dict[str, Any], *, project_root: Optional[str] = None,
     if not path and cand_look and not cand_look.startswith(("blend://", "psx://")):
         for cand in local_candidates(cand_look, bases):
             if os.path.isfile(cand) or os.path.isdir(cand):
+                # in the cloud: never opened (a read would download it)
+                if os.path.isfile(cand) and in_cloud(cand):
+                    cloud_at = cloud_at or cand
+                    continue
                 if os.path.isfile(cand) and is_empty_copy(cand):
                     empty = empty or cand
                     continue
                 path = cand
                 break
-        positions.append({"kind": "path", "where": path or empty or cand_look,
-                          "ok": bool(path)})
+        positions.append({"kind": "path", "where": path or cloud_at or empty or cand_look,
+                          "ok": bool(path), **({"cloud": True} if cloud_at and not path else {})})
     elif locator.startswith(("blend://", "psx://")) and not look:
         positions.append({"kind": "path", "where": locator, "ok": None})
     changed, now = False, ""
@@ -229,8 +253,14 @@ def resolve(entry: Dict[str, Any], *, project_root: Optional[str] = None,
         state = "on_disk"
     elif node_has:
         state = "on_node"
-        if empty:
+        if cloud_at:
+            note = f"the copy here is in the cloud, not downloaded: {cloud_at}"
+        elif empty:
             note = f"the copy here is empty: {empty}"
+    elif cloud_at:
+        state = "in_cloud"
+        note = (f"in the cloud, not downloaded: {os.path.basename(cloud_at)} — "
+                f"download it to measure or verify it")
     elif empty:
         state = "empty_copy"
         note = (f"the bytes of {os.path.basename(empty)} are zeros: an incomplete copy "
@@ -243,6 +273,8 @@ def resolve(entry: Dict[str, Any], *, project_root: Optional[str] = None,
                 else "the graph does not say where the file is")
     out = {"id": rid, "sha256": f"sha256:{hexd}" if hexd else "", "state": state,
            "path": path or "", "positions": positions, "note": note}
+    if cloud_at and not path:
+        out["cloud_path"] = cloud_at
     if changed:
         out["changed"] = True
         out["sha256_now"] = f"sha256:{now}"
@@ -322,7 +354,7 @@ def resolve_graph(graph: Any, **kwargs) -> List[Dict[str, Any]]:
         if not states:
             continue
         rank = {s: i for i, s in enumerate(("missing", "empty_copy", "reference_only",
-                                             "on_node", "both", "on_disk"))}
+                                             "in_cloud", "on_node", "both", "on_disk"))}
         worst = min(states, key=lambda s: rank.get(s, 0))
         if all(s in ("on_disk", "both") for s in states):
             worst = "both" if all(s == "both" for s in states) else "on_disk"

s3dgraphy-1.6.0.dev85/src/s3dgraphy/resources/tileset_fit.py

@@ -0,0 +1,144 @@
+"""Does a tileset fit a target? Its tiles measured one by one, from their
+heads only (MICRO-ARCHIVE-ASSET-3, E.D. 1 Nov 2026).
+
+E.D.: the tileset's row said «ok» for every target because «a tileset is its
+own lowest level»; it is «ok» for a target only if its TILES respect the
+target's band — texture and triangles per tile, read from the tileset.json or
+the .3tz without downloading all of it.
+
+A viewer streams a tileset tile by tile: what must fit the band per object is
+one tile (the triangles of its glb, the side of its largest texture), not the
+whole. Here each tile is read by its head: the b3dm / i3dm wrapper, the glb's
+JSON chunk (its accessors say the counts, a Draco primitive's too) and the
+first bytes of each image (its side) — never the geometry, never the pixels.
+
+Pure: the caller gives ``read_at(path, offset, length) -> bytes`` (a range of
+a file inside the tileset: a folder or a stored member of a .3tz) and the tree
+(:func:`.detail.read_tileset`). Nothing is written.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+#: read_at(path inside the tileset, offset, length) -> the bytes (fewer at the end)
+ReadAt = Callable[[str, int, int], bytes]
+
+#: the bytes read of an image to know its side (a JPEG's SOF may follow EXIF)
+IMAGE_HEAD = 65536
+
+#: the tiles a model can carry (a .json is an external tileset, spliced)
+TILE_EXT = (".b3dm", ".i3dm", ".glb", ".gltf")
+
+
+def tile_head(read_at: ReadAt, path: str) -> Optional[Dict[str, Any]]:
+    """Triangles and texture side of ONE tile from its head → ``{triangles,
+    texture_side, texture_px, images}``; None when it is not a glb tile (a
+    point cloud, a composite) or cannot be read."""
+    from .use_profiles import image_size
+    try:
+        head = read_at(path, 0, 32)
+        if len(head) < 12:
+            return None
+        off = 0
+        if head[:4] == b"b3dm":
+            _m, _v, _len, ftj, ftb, btj, btb = struct.unpack("<4sIIIIII", head[:28])
+            off = 28 + ftj + ftb + btj + btb
+        elif head[:4] == b"i3dm":
+            hdr = struct.unpack("<4sIIIIIII", head[:32])
+            if hdr[7] != 1:          # a uri, not an embedded glb
+                return None
+            off = 32 + hdr[3] + hdr[4] + hdr[5] + hdr[6]
+        elif head[:4] != b"glTF":
+            return None
+        gh = read_at(path, off, 20)
+        if gh[:4] != b"glTF" or len(gh) < 20:
+            return None
+        jlen, jtyp = struct.unpack("<II", gh[12:20])
+        if jtyp != 0x4E4F534A:
+            return None
+        js = json.loads(read_at(path, off + 20, jlen).decode("utf-8"))
+        bin_at = off + 20 + jlen + 8          # the BIN chunk's data
+    except (ValueError, struct.error, OSError, UnicodeDecodeError):
+        return None
+    acc = js.get("accessors") or []
+    tris = 0
+    for mesh in js.get("meshes") or []:
+        for p in mesh.get("primitives") or []:
+            if p.get("mode", 4) != 4:
+                continue
+            pos = (p.get("attributes") or {}).get("POSITION")
+            nv = int(acc[pos]["count"]) if pos is not None and pos < len(acc) else 0
+            idx = p.get("indices")
+            tris += (int(acc[idx]["count"]) if idx is not None and idx < len(acc) else nv) // 3
+    side = px = 0
+    views = js.get("bufferViews") or []
+    for im in js.get("images") or []:
+        bv = im.get("bufferView")
+        if bv is None or bv >= len(views):
+            continue
+        v = views[bv]
+        try:
+            w, h, _f = image_size(read_at(path, bin_at + int(v.get("byteOffset") or 0),
+                                          min(int(v.get("byteLength") or 0), IMAGE_HEAD)))
+        except (OSError, struct.error):
+            w = h = 0
+        side = max(side, w, h)
+        px += w * h
+    return {"triangles": tris, "texture_side": side, "texture_px": px, "images": len(js.get("images") or [])}
+
+
+def tiles_of(tree: Dict[str, Any]) -> List[str]:
+    """The tiles of a tileset's tree (:func:`.detail.read_tileset`) that carry
+    a model, in the tree's order."""
+    return [n["uri"] for n in tree["nodes"].values()
+            if n.get("uri") and str(n["uri"]).lower().endswith(TILE_EXT)]
+
+
+def measure_tiles(tree: Dict[str, Any], read_at: ReadAt) -> Dict[str, Any]:
+    """Every tile of a tileset read by its head → ``{tiles, read, per_tile:
+    [[triangles, texture_side], …], max_triangles, max_texture_side}``
+    (``per_tile`` in the order of :func:`tiles_of`; a tile unread is left
+    out and counted in ``tiles - read``)."""
+    per: List[List[int]] = []
+    names = tiles_of(tree)
+    for p in names:
+        h = tile_head(read_at, p)
+        if h is not None:
+            per.append([int(h["triangles"]), int(h["texture_side"])])
+    return {"tiles": len(names), "read": len(per), "per_tile": per,
+            "max_triangles": max((x[0] for x in per), default=0),
+            "max_texture_side": max((x[1] for x in per), default=0)}
+
+
+def fit(stats: Optional[Dict[str, Any]], band: Dict[str, Any]) -> Dict[str, Any]:
+    """Do the tiles fit a band per object? → ``{ok, known, tiles, read,
+    over_triangles, over_texture, max_triangles, max_texture_side, why}``.
+    Unknown (``stats`` None, nothing read) is not ok: it is not known."""
+    obj, side = band.get("object_triangles"), band.get("object_texture_side")
+    if not stats or not stats.get("read"):
+        return {"ok": False, "known": False, "tiles": (stats or {}).get("tiles", 0), "read": 0,
+                "over_triangles": 0, "over_texture": 0, "max_triangles": None, "max_texture_side": None,
+                "why": "le tile non sono state lette: non si sa se rispettano la fascia"}
+    per: Iterable[List[int]] = stats.get("per_tile") or []
+    ot = sum(1 for t, _s in per if obj and t > obj)
+    ox = sum(1 for _t, s in per if side and s > side)
+    mt, ms = stats.get("max_triangles") or 0, stats.get("max_texture_side") or 0
+    n, r = int(stats.get("tiles") or 0), int(stats.get("read") or 0)
+    if not ot and not ox:
+        why = (f"le {r} tile rispettano la fascia (al più {mt:,} triangoli e {ms} px per tile)"
+               .replace(",", "."))
+        if r < n:
+            why += f"; {n - r} non lette"
+        return {"ok": True, "known": True, "tiles": n, "read": r, "over_triangles": 0, "over_texture": 0,
+                "max_triangles": mt, "max_texture_side": ms, "why": why}
+    parts = []
+    if ot:
+        parts.append(f"{ot} tile oltre {obj:,} triangoli (al più {mt:,})".replace(",", "."))
+    if ox:
+        parts.append(f"{ox} tile con texture oltre {side} px (al più {ms})")
+    return {"ok": False, "known": True, "tiles": n, "read": r, "over_triangles": ot, "over_texture": ox,
+            "max_triangles": mt, "max_texture_side": ms,
+            "why": f"su {r} tile: " + "; ".join(parts)}