{"record":{"id":"d0bc1daf0faffbe2","repo":"Comfy-Org/ComfyUI","slug":"file3dtosplat-unsupported-spz-version-version","errorCode":null,"errorMessage":"File3DToSplat: unsupported .spz version {version}","messagePattern":"File3DToSplat: unsupported \\.spz version (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_gaussian_splat.py","lineNumber":357,"sourceCode":"    raw = gzip.decompress(data)\n    if struct.unpack_from('<I', raw, 0)[0] != _SPZ_MAGIC:\n        raise ValueError(\"File3DToSplat: invalid .spz (bad magic)\")\n    version = struct.unpack_from('<I', raw, 4)[0]\n    n = struct.unpack_from('<I', raw, 8)[0]\n    frac_bits = raw[13]\n    off = 16\n\n    if version == 1:\n        xyz = np.frombuffer(raw, '<f2', count=n * 3, offset=off).astype(np.float32).reshape(n, 3)\n        off += n * 6\n    elif version in (2, 3):\n        b = np.frombuffer(raw, np.uint8, count=n * 9, offset=off).reshape(n, 3, 3).astype(np.int64)\n        v = (b[..., 2] << 16) | (b[..., 1] << 8) | b[..., 0]\n        v = np.where(v & 0x800000, v - 0x1000000, v)                             # sign-extend 24-bit\n        xyz = (v / (1 << frac_bits)).astype(np.float32)\n        off += n * 9\n    else:\n        raise ValueError(f\"File3DToSplat: unsupported .spz version {version}\")\n\n    alpha = np.frombuffer(raw, np.uint8, count=n, offset=off).astype(np.float32) / 255.0\n    off += n\n    cb = np.frombuffer(raw, np.uint8, count=n * 3, offset=off).reshape(n, 3).astype(np.float32)\n    off += n * 3\n    rgb = (cb / 255.0 - 0.5) * _SPZ_COLOR_SCALE + 0.5\n    sb = np.frombuffer(raw, np.uint8, count=n * 3, offset=off).reshape(n, 3).astype(np.float32)\n    off += n * 3\n    scale = np.exp(sb / 16.0 - 10.0)\n\n    if version == 3:                                                             # smallest-three quaternion\n        qb = np.frombuffer(raw, np.uint8, count=n * 4, offset=off).reshape(n, 4).astype(np.int64)\n        combined = qb[:, 0] | (qb[:, 1] << 8) | (qb[:, 2] << 16) | (qb[:, 3] << 24)\n        largest = (combined >> 30) & 3\n        q = np.zeros((n, 4), np.float32)                                         # x,y,z,w\n        remaining, sumsq = combined.copy(), np.zeros(n, np.float64)\n        for comp in (3, 2, 1, 0):\n            active = comp != largest","sourceCodeStart":339,"sourceCodeEnd":375,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_gaussian_splat.py#L339-L375","documentation":"Raised by _parse_spz_gaussian when the version field of the decompressed .spz header is not 1, 2, or 3. Version 1 stores half-float positions, versions 2-3 use 24-bit fixed-point positions (v3 adds smallest-three quaternion encoding); anything else is a format generation the reader does not implement.","triggerScenarios":"File3DToSplat on an .spz written by a newer spz spec revision (version >= 4) or a corrupted version field; the magic matched, so the file is structurally spz-like but of an unknown generation.","commonSituations":"Niantic/spz format evolution after this reader was written; byte-level header corruption; experimental writers using custom version numbers.","solutions":["Re-export as .ply (universally supported) from the tool holding the original data.","Check for a ComfyUI update that adds support for the newer spz version.","Convert the spz with the official spz tooling down to a supported version if available."],"exampleFix":"null","handlingStrategy":"try-catch","validationCode":"import gzip, struct\nraw = gzip.decompress(open(path, 'rb').read())\nversion = struct.unpack_from('<I', raw, 4)[0]\nif version not in (1, 2, 3):\n    raise ValueError(f'spz version {version} unsupported; re-export as ply')","typeGuard":"def spz_version_supported(data: bytes) -> bool:\n    raw = gzip.decompress(data)\n    return struct.unpack_from('<I', raw, 4)[0] in (1, 2, 3)","tryCatchPattern":"try:\n    result = _parse_spz_gaussian(data)\nexcept ValueError as e:\n    if 'unsupported .spz version' in str(e):\n        re_export_as_ply(path)\n    else:\n        raise","preventionTips":["Archive interchange assets as .ply; spz support tracks a moving spec (v1-v3 here).","Watch ComfyUI updates when the spz format gains new versions."],"tags":["gaussian-splatting","spz","version-mismatch","file-format"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}