fivefury 0.2.8__tar.gz → 0.2.9__tar.gz

{fivefury-0.2.8 → fivefury-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fivefury
-Version: 0.2.8
+Version: 0.2.9
 Summary: Python library for GTA V asset workflows including YMAP, YTYP, RPF, YTD and GameFileCache utilities.
 Author: Codex
 License-Expression: CC0-1.0
@@ -42,6 +42,7 @@ The Assimp-backed import helpers (`assimp_to_ydr`, `obj_to_ydr`, `fbx_to_ydr`, `
 | `YTD` | Full | Texture dictionaries: read/write, extraction, embedded-asset helpers |
 | `YND` | Full | Path nodes, links, area partitioning, junction heightmaps |
 | `YNV` | Full | Navmeshes: sectors, polys, portals, validation, basic OBJ partitioning |
+| `heightmap.dat` | Full | World-height grids, native quantization, row RLE, water masks, spatial queries |
 | `water.xml` | Full | Water surfaces, triangle corners, calming regions, wave amplitude and direction |
 | `CUT` | Full | Cutscenes, plus the readable `.cuts` script format for round-trip authoring |
 | `GXT2` | Full | Hashed text tables with binary read/write and text import/export |
@@ -140,6 +141,21 @@ water.add(
 water.translate(x=500, y=-200, z=20.0).save("water.xml")
 ```
 
+### Author a world height map
+
+```python
+from fivefury import HeightMap, HeightMapBounds
+
+heightmap = HeightMap.empty(
+    columns=10,
+    rows=10,
+    bounds=HeightMapBounds(0.0, 0.0, 0.0, 500.0, 500.0, 800.0),
+)
+heightmap.set_height(4, 6, minimum=32.0, maximum=78.0)
+heightmap.set_water(4, 6)
+heightmap.save("heightmap.dat")
+```
+
 ### Convert audio to AWC
 
 ```python

fivefury-0.2.8/fivefury.egg-info/PKG-INFO → fivefury-0.2.9/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.4
-Name: fivefury
-Version: 0.2.8
-Summary: Python library for GTA V asset workflows including YMAP, YTYP, RPF, YTD and GameFileCache utilities.
-Author: Codex
-License-Expression: CC0-1.0
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: miniaudio>=1.71
-Requires-Dist: numpy>=1.26
-Dynamic: license-file
-
 # FiveFury
 
 FiveFury is a Python library for reading, writing, and packaging GTA V asset files: drawables, collisions, map metadata, animations, navigation data, texture dictionaries, text tables, audio containers, cutscenes, DLC metadata, and RPF archives.
@@ -42,6 +29,7 @@ The Assimp-backed import helpers (`assimp_to_ydr`, `obj_to_ydr`, `fbx_to_ydr`, `
 | `YTD` | Full | Texture dictionaries: read/write, extraction, embedded-asset helpers |
 | `YND` | Full | Path nodes, links, area partitioning, junction heightmaps |
 | `YNV` | Full | Navmeshes: sectors, polys, portals, validation, basic OBJ partitioning |
+| `heightmap.dat` | Full | World-height grids, native quantization, row RLE, water masks, spatial queries |
 | `water.xml` | Full | Water surfaces, triangle corners, calming regions, wave amplitude and direction |
 | `CUT` | Full | Cutscenes, plus the readable `.cuts` script format for round-trip authoring |
 | `GXT2` | Full | Hashed text tables with binary read/write and text import/export |
@@ -140,6 +128,21 @@ water.add(
 water.translate(x=500, y=-200, z=20.0).save("water.xml")
 ```
 
+### Author a world height map
+
+```python
+from fivefury import HeightMap, HeightMapBounds
+
+heightmap = HeightMap.empty(
+    columns=10,
+    rows=10,
+    bounds=HeightMapBounds(0.0, 0.0, 0.0, 500.0, 500.0, 800.0),
+)
+heightmap.set_height(4, 6, minimum=32.0, maximum=78.0)
+heightmap.set_water(4, 6)
+heightmap.save("heightmap.dat")
+```
+
 ### Convert audio to AWC
 
 ```python

{fivefury-0.2.8 → fivefury-0.2.9}/fivefury/__init__.py

@@ -459,6 +459,20 @@ from .rpf import (
     zip_to_rpf,
 )
 from .texture import BCFormat
+from .heightmap import (
+    HeightCell,
+    HeightGrid,
+    HeightMap,
+    HeightMapBounds,
+    HeightMapByteOrder,
+    HeightMapCellFormat,
+    HeightMapFlags,
+    HeightMapValidationError,
+    build_heightmap_bytes,
+    create_heightmap,
+    read_heightmap,
+    save_heightmap,
+)
 from .water import (
     WaterAlpha,
     WaterBounds,
@@ -1218,6 +1232,14 @@ __all__ = [
     "GameTarget",
     "GameCrypto",
     "GameFileType",
+    "HeightCell",
+    "HeightGrid",
+    "HeightMap",
+    "HeightMapBounds",
+    "HeightMapByteOrder",
+    "HeightMapCellFormat",
+    "HeightMapFlags",
+    "HeightMapValidationError",
     "GXT2_MAGIC",
     "GXT2_MAGIC_BYTES",
     "Gxt2",
@@ -1594,6 +1616,7 @@ __all__ = [
     "infer_archetype_radius",
     "mark_cutscene_prop_archetypes",
     "assimp_to_ydr",
+    "build_heightmap_bytes",
     "build_rsc7",
     "build_water_xml",
     "build_ynv_bytes",
@@ -1617,6 +1640,7 @@ __all__ = [
     "clear_hash_resolver",
     "clear_game_crypto",
     "create_rpf",
+    "create_heightmap",
     "create_water",
     "create_ymf_for_ymaps",
     "create_ydd",
@@ -1701,6 +1725,7 @@ __all__ = [
     "read_ymap",
     "read_vehicle_meta",
     "read_water",
+    "read_heightmap",
     "read_ymf",
     "read_ymf_xml",
     "read_ymt",
@@ -1731,6 +1756,7 @@ __all__ = [
     "save_ytd",
     "save_ytyp",
     "save_water",
+    "save_heightmap",
     "set_ped_drawable_cloth",
     "time_flags",
     "save_cut",

{fivefury-0.2.8 → fivefury-0.2.9}/fivefury/bounds/model.py

@@ -1054,7 +1054,7 @@ class BoundGeometry(Bound):
         return material
 
     def build(self) -> "BoundGeometry":
-        super().build()
+        Bound.build(self)
         for index, polygon in enumerate(self.polygons):
             polygon.index = index
             if isinstance(polygon, BoundPolygonTriangle):
@@ -1079,7 +1079,7 @@ class BoundGeometry(Bound):
         return self
 
     def validate(self) -> list[str]:
-        issues = super().validate()
+        issues = Bound.validate(self)
         if len(self.polygon_material_indices) != len(self.polygons):
             issues.append("polygon_material_indices length does not match polygon count")
         for polygon_index, polygon in enumerate(self.polygons):
@@ -1164,7 +1164,7 @@ class BoundComposite(Bound):
     def compute_volume(self) -> float:
         if self.children:
             return sum(child.bound.compute_volume() for child in self.children)
-        return super().compute_volume()
+        return Bound.compute_volume(self)
 
     def compute_center_of_gravity(
         self,
@@ -1226,7 +1226,7 @@ class BoundComposite(Bound):
         return self.compute_composite_angular_inertia(mass)
 
     def build(self) -> "BoundComposite":
-        super().build()
+        Bound.build(self)
         for child in self.children:
             child.bound.build()
             if child.bounds is None or not _aabb_is_valid(child.bounds):
@@ -1252,7 +1252,7 @@ class BoundComposite(Bound):
         return self
 
     def validate(self) -> list[str]:
-        issues = super().validate()
+        issues = Bound.validate(self)
         if not self.children:
             issues.append("Composite bound has no children")
         for index, child in enumerate(self.children):

{fivefury-0.2.8 → fivefury-0.2.9}/fivefury/cache/core.py

@@ -554,6 +554,7 @@ _KIND_DICT_TYPES: dict[str, GameFileType] = {
     "GtxdDict": GameFileType.GTXD,
     "AwcDict": GameFileType.AWC,
     "YedDict": GameFileType.YED,
+    "HeightMapDict": GameFileType.HEIGHTMAP,
     "WaterDict": GameFileType.WATER,
     "WaterMapDict": GameFileType.WATER,
 }

{fivefury-0.2.8 → fivefury-0.2.9}/fivefury/cache/io.py

@@ -10,6 +10,7 @@ from ..cut import read_cut
 from ..gamefile import GameFile, GameFileType, guess_game_file_type
 from ..gtxd import read_gtxd
 from ..gxt2 import read_gxt2
+from ..heightmap import read_heightmap
 from ..hashing import _get_lut
 from ..metahash import MetaHash
 from ..rel import read_rel
@@ -66,6 +67,8 @@ def _decode_dynamic(data: bytes, *, module_name: str, attribute: str, kind: Game
 def _decode_payload(path: str, data: bytes, *, raw: bytes | None = None) -> tuple[Any, GameFileType]:
     ext = Path(path).suffix.lower()
     name = Path(path).name.lower()
+    if name.startswith("heightmap") and name.endswith(".dat"):
+        return _decode_or_fallback(GameFileType.HEIGHTMAP, data, data, read_heightmap)
     if name == "water.xml":
         return _decode_or_fallback(GameFileType.WATER, data, data, read_water)
     if name == "gtxd.meta":

{fivefury-0.2.8 → fivefury-0.2.9}/fivefury/cache/scan.py

@@ -15,7 +15,7 @@ from ..gamefile import GameFileType, guess_game_file_type
 from ..hashing import _get_lut
 from ..rpf import RpfArchive, RpfFileEntry, _normalize_key
 
-_SCAN_INDEX_VERSION = 9
+_SCAN_INDEX_VERSION = 10
 _SCAN_GC_INTERVAL = 8
 
 _FLAG_LOOSE = 1

{fivefury-0.2.8 → fivefury-0.2.9}/fivefury/cdr/model.py

@@ -284,7 +284,7 @@ class Cdr(DrawableAsset[CdrMaterial, CdrModel, CdrMesh]):
     graphics_data: bytes = dataclasses.field(default=b"", repr=False)
 
     def __post_init__(self) -> None:
-        super().__post_init__()
+        DrawableAsset.__post_init__(self)
         self.render_bucket_masks = {
             DrawableLod(lod): int(mask)
             for lod, mask in self.render_bucket_masks.items()

{fivefury-0.2.8 → fivefury-0.2.9}/fivefury/gamefile.py

@@ -80,6 +80,9 @@ _FILE_TYPE_MAP: dict[str, GameFileType] = {
 
 def guess_game_file_type(path: str | Path, default: GameFileType = GameFileType.UNKNOWN) -> GameFileType:
     parsed = Path(str(path))
+    normalized_name = parsed.name.lower()
+    if normalized_name.startswith("heightmap") and normalized_name.endswith(".dat"):
+        return GameFileType.HEIGHTMAP
     named_meta_types = {
         "gtxd.meta": GameFileType.GTXD,
         "vehicles.meta": GameFileType.VEHICLES,
@@ -91,7 +94,7 @@ def guess_game_file_type(path: str | Path, default: GameFileType = GameFileType.
         "peds.meta": GameFileType.PEDS,
         "water.xml": GameFileType.WATER,
     }
-    named_type = named_meta_types.get(parsed.name.lower())
+    named_type = named_meta_types.get(normalized_name)
     if named_type is not None:
         return named_type
     return _FILE_TYPE_MAP.get(parsed.suffix.lower(), default)

fivefury-0.2.9/fivefury/heightmap/__init__.py

@@ -0,0 +1,31 @@
+from .io import (
+    build_heightmap_bytes,
+    create_heightmap,
+    read_heightmap,
+    save_heightmap,
+)
+from .model import (
+    HeightCell,
+    HeightGrid,
+    HeightMap,
+    HeightMapBounds,
+    HeightMapByteOrder,
+    HeightMapCellFormat,
+    HeightMapFlags,
+    HeightMapValidationError,
+)
+
+__all__ = [
+    "HeightCell",
+    "HeightGrid",
+    "HeightMap",
+    "HeightMapBounds",
+    "HeightMapByteOrder",
+    "HeightMapCellFormat",
+    "HeightMapFlags",
+    "HeightMapValidationError",
+    "build_heightmap_bytes",
+    "create_heightmap",
+    "read_heightmap",
+    "save_heightmap",
+]

fivefury-0.2.9/fivefury/heightmap/io.py

@@ -0,0 +1,373 @@
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+from .model import (
+    HeightCell,
+    HeightGrid,
+    HeightMap,
+    HeightMapBounds,
+    HeightMapByteOrder,
+    HeightMapCellFormat,
+    HeightMapFlags,
+)
+
+_HEADER_SIZE = 44
+_RLE_ROW_SIZE = 8
+_TAG = b"HMAP"
+_REVERSED_TAG = _TAG[::-1]
+
+
+def _source_bytes(source: bytes | bytearray | memoryview | str | Path) -> bytes:
+    if isinstance(source, (bytes, bytearray, memoryview)):
+        return bytes(source)
+    return Path(source).read_bytes()
+
+
+def _endian_prefix(order: HeightMapByteOrder) -> str:
+    return ">" if order is HeightMapByteOrder.BIG else "<"
+
+
+def _cell_format(cell_format: HeightMapCellFormat) -> str:
+    return {
+        HeightMapCellFormat.UINT8: "B",
+        HeightMapCellFormat.UINT16: "H",
+        HeightMapCellFormat.FLOAT32: "f",
+    }[cell_format]
+
+
+def _unpack_cells(
+    data: bytes,
+    offset: int,
+    count: int,
+    *,
+    endian: str,
+    cell_format: HeightMapCellFormat,
+) -> tuple[list[HeightCell], int]:
+    size = int(cell_format)
+    end = offset + count * size
+    if end > len(data):
+        raise ValueError("height-map cell data is truncated")
+    if count == 0:
+        return [], end
+    values = struct.unpack_from(
+        f"{endian}{count}{_cell_format(cell_format)}", data, offset
+    )
+    return list(values), end
+
+
+def _pack_cells(
+    values: list[HeightCell],
+    *,
+    endian: str,
+    cell_format: HeightMapCellFormat,
+) -> bytes:
+    if not values:
+        return b""
+    return struct.pack(
+        f"{endian}{len(values)}{_cell_format(cell_format)}",
+        *values,
+    )
+
+
+def _unpack_water_mask(data: bytes, cell_count: int) -> list[bool]:
+    return [bool(data[index // 8] & (1 << (index % 8))) for index in range(cell_count)]
+
+
+def _pack_water_mask(cells: list[bool]) -> bytes:
+    result = bytearray((len(cells) + 7) // 8)
+    for index, enabled in enumerate(cells):
+        if enabled:
+            result[index // 8] |= 1 << (index % 8)
+    return bytes(result)
+
+
+def read_heightmap(
+    source: bytes | bytearray | memoryview | str | Path,
+) -> HeightMap:
+    data = _source_bytes(source)
+    if len(data) < _HEADER_SIZE:
+        raise ValueError("height-map data is shorter than its 44-byte header")
+    if data[:4] == _TAG:
+        order = HeightMapByteOrder.BIG
+    elif data[:4] == _REVERSED_TAG:
+        order = HeightMapByteOrder.LITTLE
+    else:
+        raise ValueError("height-map data does not start with the HMAP tag")
+
+    endian = _endian_prefix(order)
+    (
+        _,
+        version,
+        cell_size,
+        raw_flags,
+        columns,
+        rows,
+        min_x,
+        min_y,
+        min_z,
+        max_x,
+        max_y,
+        max_z,
+        data_size,
+    ) = struct.unpack_from(f"{endian}4sBB2xIHH6fI", data)
+    try:
+        cell_format = HeightMapCellFormat(cell_size)
+    except ValueError as exc:
+        raise ValueError(f"unsupported height-map cell size: {cell_size}") from exc
+    if not 1 <= columns <= 1000 or not 1 <= rows <= 1000:
+        raise ValueError("height-map dimensions must be between 1 and 1000 cells")
+
+    flags = HeightMapFlags(raw_flags)
+    mask_size = (columns * rows + 7) // 8 if flags & HeightMapFlags.WATER_MASK else 0
+    expected_size = _HEADER_SIZE + data_size + mask_size
+    if len(data) != expected_size:
+        raise ValueError(
+            f"height-map size mismatch: header describes {expected_size} bytes, got {len(data)}"
+        )
+
+    payload = data[_HEADER_SIZE : _HEADER_SIZE + data_size]
+    cell_count = columns * rows
+    empty: HeightCell = 0.0 if cell_format is HeightMapCellFormat.FLOAT32 else 0
+    minimum_cells = [empty] * cell_count
+    maximum_cells = [empty] * cell_count
+
+    if flags & HeightMapFlags.RLE_DATA:
+        table_size = rows * _RLE_ROW_SIZE
+        if len(payload) < table_size:
+            raise ValueError("height-map RLE table is truncated")
+        compact_bytes = len(payload) - table_size
+        pair_size = int(cell_format) * 2
+        if compact_bytes % pair_size:
+            raise ValueError(
+                "height-map RLE payload is not aligned to min/max cell pairs"
+            )
+        compact_count = compact_bytes // pair_size
+        rle_rows = [
+            struct.unpack_from(f"{endian}HHi", payload, row * _RLE_ROW_SIZE)
+            for row in range(rows)
+        ]
+        offset = table_size
+        maximum_compact, offset = _unpack_cells(
+            payload,
+            offset,
+            compact_count,
+            endian=endian,
+            cell_format=cell_format,
+        )
+        minimum_compact, offset = _unpack_cells(
+            payload,
+            offset,
+            compact_count,
+            endian=endian,
+            cell_format=cell_format,
+        )
+        if offset != len(payload):
+            raise ValueError("height-map RLE payload contains trailing bytes")
+
+        for row, (start, count, data_offset) in enumerate(rle_rows):
+            if start > columns or count > columns - start:
+                raise ValueError(f"height-map RLE row {row} exceeds the column count")
+            compact_start = data_offset + start
+            if compact_start < 0 or compact_start + count > compact_count:
+                raise ValueError(
+                    f"height-map RLE row {row} points outside the compact data"
+                )
+            dense_start = row * columns + start
+            dense_stop = dense_start + count
+            minimum_cells[dense_start:dense_stop] = minimum_compact[
+                compact_start : compact_start + count
+            ]
+            maximum_cells[dense_start:dense_stop] = maximum_compact[
+                compact_start : compact_start + count
+            ]
+    else:
+        expected_data_size = cell_count * int(cell_format) * 2
+        if data_size != expected_data_size:
+            raise ValueError(
+                f"height-map cell payload should contain {expected_data_size} bytes, got {data_size}"
+            )
+        maximum_cells, offset = _unpack_cells(
+            payload,
+            0,
+            cell_count,
+            endian=endian,
+            cell_format=cell_format,
+        )
+        minimum_cells, offset = _unpack_cells(
+            payload,
+            offset,
+            cell_count,
+            endian=endian,
+            cell_format=cell_format,
+        )
+        if offset != len(payload):
+            raise ValueError("height-map cell payload contains trailing bytes")
+
+    water_cells = None
+    if mask_size:
+        water_cells = _unpack_water_mask(data[-mask_size:], cell_count)
+
+    result = HeightMap(
+        columns=columns,
+        rows=rows,
+        bounds=HeightMapBounds(min_x, min_y, min_z, max_x, max_y, max_z),
+        minimum_cells=minimum_cells,
+        maximum_cells=maximum_cells,
+        water_cells=water_cells,
+        cell_format=cell_format,
+        version=version,
+        flags=flags,
+        source_byte_order=order,
+    )
+    result.ensure_valid(game_compatible=False)
+    return result
+
+
+def _compact_rows(
+    heightmap: HeightMap,
+) -> tuple[list[tuple[int, int, int]], list[HeightCell], list[HeightCell]]:
+    rows: list[tuple[int, int, int]] = []
+    maximum: list[HeightCell] = []
+    minimum: list[HeightCell] = []
+    compact_count = 0
+    ranges: list[tuple[int, int]] = []
+
+    for row in range(heightmap.rows):
+        row_offset = row * heightmap.columns
+        start = 0
+        stop = heightmap.columns - 1
+        while start < heightmap.columns:
+            index = row_offset + start
+            if (
+                heightmap.minimum_cells[index] != 0
+                or heightmap.maximum_cells[index] != 0
+            ):
+                break
+            start += 1
+        while stop >= start:
+            index = row_offset + stop
+            if (
+                heightmap.minimum_cells[index] != 0
+                or heightmap.maximum_cells[index] != 0
+            ):
+                break
+            stop -= 1
+        count = max(0, stop - start + 1)
+        rows.append(
+            (start if count else 0, count, compact_count - start if count else 0)
+        )
+        ranges.append((row_offset + start, count))
+        compact_count += count
+
+    for start, count in ranges:
+        maximum.extend(heightmap.maximum_cells[start : start + count])
+    for start, count in ranges:
+        minimum.extend(heightmap.minimum_cells[start : start + count])
+    return rows, maximum, minimum
+
+
+def build_heightmap_bytes(
+    source: HeightMap,
+    *,
+    rle: bool | None = None,
+    byte_order: HeightMapByteOrder = HeightMapByteOrder.BIG,
+    game_compatible: bool = True,
+) -> bytes:
+    heightmap = source.build().ensure_valid(game_compatible=game_compatible)
+    order = HeightMapByteOrder(byte_order)
+    endian = _endian_prefix(order)
+    use_rle = heightmap.uses_rle if rle is None else bool(rle)
+
+    if use_rle:
+        rows, maximum, minimum = _compact_rows(heightmap)
+        table = b"".join(struct.pack(f"{endian}HHi", *row) for row in rows)
+        payload = (
+            table
+            + _pack_cells(maximum, endian=endian, cell_format=heightmap.cell_format)
+            + _pack_cells(minimum, endian=endian, cell_format=heightmap.cell_format)
+        )
+    else:
+        payload = _pack_cells(
+            heightmap.maximum_cells,
+            endian=endian,
+            cell_format=heightmap.cell_format,
+        ) + _pack_cells(
+            heightmap.minimum_cells,
+            endian=endian,
+            cell_format=heightmap.cell_format,
+        )
+
+    flags = int(heightmap.flags)
+    if use_rle:
+        flags |= int(HeightMapFlags.RLE_DATA)
+    else:
+        flags &= ~int(HeightMapFlags.RLE_DATA)
+    if heightmap.water_cells is not None:
+        flags |= int(HeightMapFlags.WATER_MASK)
+        water_mask = _pack_water_mask(heightmap.water_cells)
+    else:
+        flags &= ~int(HeightMapFlags.WATER_MASK)
+        water_mask = b""
+
+    tag = _TAG if order is HeightMapByteOrder.BIG else _REVERSED_TAG
+    bounds = heightmap.bounds
+    header = struct.pack(
+        f"{endian}4sBB2xIHH6fI",
+        tag,
+        heightmap.version,
+        int(heightmap.cell_format),
+        flags,
+        heightmap.columns,
+        heightmap.rows,
+        bounds.min_x,
+        bounds.min_y,
+        bounds.min_z,
+        bounds.max_x,
+        bounds.max_y,
+        bounds.max_z,
+        len(payload),
+    )
+    return header + payload + water_mask
+
+
+def create_heightmap(
+    minimum: HeightGrid,
+    maximum: HeightGrid | None = None,
+    *,
+    bounds: HeightMapBounds | tuple[float, float, float, float, float, float],
+    water: list[list[bool]] | None = None,
+    cell_format: HeightMapCellFormat = HeightMapCellFormat.UINT8,
+) -> HeightMap:
+    return HeightMap.from_height_grids(
+        minimum,
+        maximum,
+        bounds=bounds,
+        water=water,
+        cell_format=cell_format,
+    )
+
+
+def save_heightmap(
+    source: HeightMap,
+    destination: str | Path,
+    *,
+    rle: bool | None = None,
+    byte_order: HeightMapByteOrder = HeightMapByteOrder.BIG,
+    game_compatible: bool = True,
+) -> Path:
+    return source.save(
+        destination,
+        rle=rle,
+        byte_order=byte_order,
+        game_compatible=game_compatible,
+    )
+
+
+__all__ = [
+    "build_heightmap_bytes",
+    "create_heightmap",
+    "read_heightmap",
+    "save_heightmap",
+]