fractex 0.1.0__py3-none-any.whl

fractex/examples/3d.py

@@ -0,0 +1,109 @@
+import sys
+from pathlib import Path
+import numpy as np
+import argparse
+from dataclasses import dataclass
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+EXAMPLES_DIR = Path(__file__).resolve().parent
+if str(EXAMPLES_DIR) not in sys.path:
+    sys.path.insert(0, str(EXAMPLES_DIR))
+
+from fractex.volume_textures import (
+    VolumeTextureGenerator3D,
+    VolumeTextureBlender3D,
+    VolumeTextureRenderer,
+    VolumeTexture3D,
+    VolumeFormat,
+)
+from _output import save_ppm, save_mp4
+from fractex.interactive import add_interactive_args, InteractiveConfig, run_interactive
+
+
+@dataclass
+class Player:
+    position: np.ndarray
+    look_at: np.ndarray
+
+
+def main():
+    parser = argparse.ArgumentParser(description="3D volume example")
+    add_interactive_args(parser)
+    args = parser.parse_args()
+    game_time = 0.0
+    player = Player(
+        position=np.array([0.5, 0.5, 2.0]),
+        look_at=np.array([0.5, 0.5, 0.5])
+    )
+    
+    # Создание объемного облачного неба
+    generator = VolumeTextureGenerator3D(seed=42)
+    cloud_volume = generator.generate_clouds_3d(
+        width=64, height=32, depth=64,
+        scale=0.02, density=0.4, animated=False, time=game_time
+    )
+    
+    # Создание подземной пещеры с лавой
+    cave_noise = generator.generate_perlin_3d(
+        width=48, height=48, depth=48,
+        scale=0.03, octaves=3
+    )
+    
+    lava_pockets = generator.generate_lava_3d(
+        width=48, height=48, depth=48,
+        scale=0.01, temperature=0.8, animated=False, time=game_time
+    )
+    
+    # Смешивание пещеры и лавы
+    blender = VolumeTextureBlender3D()
+    cave_mask = (cave_noise.data > 0.7).astype(np.float32)
+    cave_rgba = VolumeTexture3D(
+        data=np.repeat(cave_noise.data, 4, axis=3),
+        format=VolumeFormat.RGBA_FLOAT,
+        voxel_size=cave_noise.voxel_size,
+    )
+    cave_with_lava = blender.blend(
+        cave_rgba, lava_pockets,
+        blend_mode="add",
+        blend_mask=cave_mask
+    )
+    
+    # Рендеринг
+    renderer = VolumeTextureRenderer(cave_with_lava)
+    frames = []
+    for z in [2.2, 2.0, 1.8, 1.6, 1.4, 1.2]:
+        camera_pos = np.array([0.5, 0.5, z])
+        frame = renderer.render_raycast(
+            camera_pos=camera_pos,
+            camera_target=player.look_at,
+            image_size=(256, 144),
+            max_steps=64
+        )
+        frames.append(frame)
+    
+    print("Cloud volume:", cloud_volume.data.shape)
+    print("Cave with lava:", cave_with_lava.data.shape)
+    print("Rendered frame:", frames[0].shape)
+    if float(frames[0].max()) == 0.0:
+        projection = cave_with_lava.data[..., 3].max(axis=0)
+        save_ppm(projection, EXAMPLES_DIR / "output" / "3d_raycast.ppm", stretch=True)
+    else:
+        save_ppm(frames[0], EXAMPLES_DIR / "output" / "3d_raycast.ppm", stretch=True)
+    save_mp4(frames, EXAMPLES_DIR / "output" / "3d_raycast.mp4", fps=8, stretch=True)
+    
+    if args.interactive:
+        config = InteractiveConfig.from_args(args, title="3D Raycast (interactive)")
+        depth = cave_with_lava.data.shape[0]
+        
+        def render_frame(t, w, h):
+            idx = int(abs(np.sin(t * 0.2)) * (depth - 1))
+            slice_img = cave_with_lava.data[idx]
+            return slice_img[..., :3]
+        
+        run_interactive(render_frame, config)
+
+
+if __name__ == "__main__":
+    main()

fractex/examples/3d_integration.py

@@ -0,0 +1,113 @@
+# Полный пайплайн: текстура + рассеяние
+import sys
+from pathlib import Path
+import numpy as np
+import argparse
+from dataclasses import dataclass
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+EXAMPLES_DIR = Path(__file__).resolve().parent
+if str(EXAMPLES_DIR) not in sys.path:
+    sys.path.insert(0, str(EXAMPLES_DIR))
+
+from fractex.volume_textures import VolumeTextureGenerator3D
+from fractex.volume_scattering import VolumeScatteringRenderer, MediumProperties, LightSource
+from _output import save_ppm, save_mp4
+from fractex.interactive import add_interactive_args, InteractiveConfig, run_interactive
+
+
+@dataclass
+class Player:
+    position: np.ndarray
+    look_at: np.ndarray
+
+
+def blend_volume_with_scene(scene_image: np.ndarray, volume_image: np.ndarray, weight: float = 0.6) -> np.ndarray:
+    return np.clip(scene_image * (1.0 - weight) + volume_image * weight, 0, 1)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="3D integration example")
+    add_interactive_args(parser)
+    args = parser.parse_args()
+    # Генерация объемной текстуры облаков
+    generator = VolumeTextureGenerator3D(seed=42)
+    clouds_3d = generator.generate_clouds_3d(
+        width=64, height=32, depth=64,
+        scale=0.02, density=0.3, animated=False
+    )
+    
+    # Настройка атмосферного рассеяния
+    atmosphere = MediumProperties(
+        scattering_coefficient=0.08,
+        absorption_coefficient=0.02,
+        phase_function_g=0.7,
+        density=1.0,
+        color=(1.0, 0.95, 0.9)
+    )
+    
+    # Солнечный свет
+    sun = LightSource(
+        direction=np.array([0.2, 0.9, 0.1]),
+        color=(1.0, 0.95, 0.9),
+        intensity=1.0,
+        light_type="directional"
+    )
+    
+    player = Player(
+        position=np.array([0.5, 0.5, -1.0]),
+        look_at=np.array([0.5, 0.5, 0.5])
+    )
+    
+    frames = []
+    directions = [
+        np.array([0.3, 0.9, 0.1]),
+        np.array([0.1, 0.9, 0.3]),
+        np.array([-0.1, 0.9, 0.3]),
+        np.array([-0.3, 0.9, 0.1]),
+        np.array([0.0, 0.7, 0.7]),
+        np.array([0.0, 0.6, 0.8]),
+    ]
+    for direction in directions:
+        sun.direction = direction
+        renderer = VolumeScatteringRenderer(
+            volume=clouds_3d,
+            medium=atmosphere,
+            light_sources=[sun],
+            use_multiple_scattering=False
+        )
+        image = renderer.render_volumetric_light(
+            camera_pos=player.position,
+            camera_target=player.look_at,
+            image_size=(320, 180),
+            max_steps=48
+        )
+        scene_image = np.zeros_like(image)
+        final_image = blend_volume_with_scene(scene_image, image)
+        frames.append(final_image)
+    
+    final_image = frames[0]
+    print("Rendered image:", final_image.shape, final_image.min(), final_image.max())
+    if float(final_image.max()) == 0.0:
+        density = clouds_3d.data[clouds_3d.data.shape[0] // 2, :, :, 3]
+        save_ppm(density, EXAMPLES_DIR / "output" / "3d_integration.ppm", stretch=True)
+    else:
+        save_ppm(final_image, EXAMPLES_DIR / "output" / "3d_integration.ppm", stretch=True)
+    save_mp4(frames, EXAMPLES_DIR / "output" / "3d_integration.mp4", fps=8, stretch=True)
+    
+    if args.interactive:
+        config = InteractiveConfig.from_args(args, title="3D Integration (interactive)")
+        depth = clouds_3d.data.shape[0]
+        
+        def render_frame(t, w, h):
+            idx = int(abs(np.sin(t * 0.2)) * (depth - 1))
+            density = clouds_3d.data[idx, :, :, 3]
+            return density
+        
+        run_interactive(render_frame, config)
+
+
+if __name__ == "__main__":
+    main()

fractex/examples/3d_integration_2d.py

@@ -0,0 +1,59 @@
+# Создание hybrid материала: 2D текстура + 3D детали
+import sys
+from pathlib import Path
+import argparse
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+EXAMPLES_DIR = Path(__file__).resolve().parent
+if str(EXAMPLES_DIR) not in sys.path:
+    sys.path.insert(0, str(EXAMPLES_DIR))
+
+from fractex.simplex_noise import SimplexTextureGenerator
+from fractex.volume_textures import VolumeTextureGenerator3D
+from _output import save_ppm
+from fractex.interactive import add_interactive_args, InteractiveConfig, run_interactive
+
+
+def main():
+    parser = argparse.ArgumentParser(description="3D integration 2D example")
+    add_interactive_args(parser)
+    args = parser.parse_args()
+    
+    # 2D terrain текстура
+    tex_gen_2d = SimplexTextureGenerator(seed=42)
+    terrain_2d = tex_gen_2d.generate_terrain(64, 64)
+    
+    # 3D детали (камни, трава)
+    tex_gen_3d = VolumeTextureGenerator3D(seed=42)
+    rocks_3d = tex_gen_3d.generate_rocks_3d(64, 64, 32)
+    grass_3d = tex_gen_3d.generate_grass_3d(64, 64, 16)
+    
+    print("Terrain 2D:", terrain_2d.shape)
+    print("Rocks 3D:", rocks_3d.data.shape)
+    print("Grass 3D:", grass_3d.data.shape)
+    
+    # Проекция 3D деталей на 2D terrain
+    # (демо — используем средний срез по глубине)
+    rocks_slice = rocks_3d.data[rocks_3d.data.shape[0] // 2, :, :, 3]
+    grass_slice = grass_3d.data[grass_3d.data.shape[0] // 2, :, :, 3]
+    combined = terrain_2d.copy()
+    combined[..., 1] = (combined[..., 1] * 0.7 + grass_slice * 0.3)
+    combined[..., 2] = (combined[..., 2] * 0.7 + rocks_slice * 0.3)
+    
+    print("Combined terrain sample:", combined[0, 0])
+    save_ppm(combined, EXAMPLES_DIR / "output" / "3d_integration_2d.ppm")
+    
+    if args.interactive:
+        config = InteractiveConfig.from_args(args, title="3D Integration 2D (interactive)")
+
+        def render_frame(t, w, h):
+            terrain = tex_gen_2d.generate_terrain(w, h)
+            return terrain[..., :3]
+        
+        run_interactive(render_frame, config)
+
+
+if __name__ == "__main__":
+    main()

fractex/examples/__init__.py

@@ -0,0 +1,34 @@
+"""Example modules for Fractex."""
+
+from __future__ import annotations
+
+import runpy
+import sys
+from typing import List, Optional
+
+
+def list_examples() -> List[str]:
+    return [
+        "splash",
+        "custom_pattern",
+        "architecture_pattern",
+        "composite_material",
+        "crystal_cave",
+        "integration",
+        "terrain",
+        "3d_integration_2d",
+        "3d_integration",
+        "3d",
+        "underwater",
+        "underwater_volkano",
+        "game_texture",
+    ]
+
+
+def run_example(name: str, args: Optional[List[str]] = None) -> None:
+    """Run an example module by name."""
+    if name not in list_examples():
+        raise ValueError(f"Unknown example '{name}'.")
+    module = f"fractex.examples.{name}"
+    sys.argv = [module] + (args or [])
+    runpy.run_module(module, run_name="__main__")

fractex/examples/_output.py

@@ -0,0 +1,115 @@
+"""Small helpers for saving example outputs without extra deps."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, Optional
+
+import numpy as np
+
+
+def _ensure_rgb(image: np.ndarray) -> np.ndarray:
+    if image.ndim == 2:
+        image = np.repeat(image[:, :, None], 3, axis=2)
+    if image.shape[2] == 1:
+        image = np.repeat(image, 3, axis=2)
+    if image.shape[2] >= 3:
+        return image[:, :, :3]
+    raise ValueError("Unsupported image shape for RGB conversion.")
+
+
+def _normalize_to_uint8(image: np.ndarray, stretch: bool) -> np.ndarray:
+    img = image.astype(np.float32)
+    if img.size == 0:
+        return img.astype(np.uint8)
+    min_val = float(img.min())
+    max_val = float(img.max())
+    if stretch and max_val > min_val:
+        img = (img - min_val) / (max_val - min_val)
+    elif min_val < 0.0 or max_val > 1.0:
+        if max_val > min_val:
+            img = (img - min_val) / (max_val - min_val)
+    img = np.clip(img, 0.0, 1.0)
+    return (img * 255.0 + 0.5).astype(np.uint8)
+
+
+def save_ppm(image: np.ndarray, path: Path, stretch: bool = False) -> None:
+    """Save an image to binary PPM (P6) format."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    rgb = _ensure_rgb(image)
+    data = _normalize_to_uint8(rgb, stretch=stretch)
+    height, width, _ = data.shape
+    header = f"P6\n{width} {height}\n255\n".encode("ascii")
+    with path.open("wb") as f:
+        f.write(header)
+        f.write(data.tobytes())
+
+
+def save_volume_slice(
+    volume: np.ndarray,
+    path: Path,
+    axis: int = 0,
+    index: Optional[int] = None,
+    stretch: bool = False,
+) -> None:
+    """Save a middle slice from a 3D/4D volume."""
+    if volume.ndim == 3:
+        data = volume
+    elif volume.ndim == 4:
+        data = volume
+    else:
+        raise ValueError("Volume must be 3D or 4D.")
+    
+    if index is None:
+        index = data.shape[axis] // 2
+    if axis == 0:
+        slice_img = data[index]
+    elif axis == 1:
+        slice_img = data[:, index, :]
+    else:
+        slice_img = data[:, :, index]
+    
+    save_ppm(slice_img, path, stretch=stretch)
+
+
+def save_ppm_sequence(
+    frames: Iterable[np.ndarray],
+    directory: Path,
+    prefix: str = "frame",
+    stretch: bool = False,
+) -> None:
+    """Save a sequence of frames as numbered PPM files."""
+    directory.mkdir(parents=True, exist_ok=True)
+    for i, frame in enumerate(frames):
+        save_ppm(frame, directory / f"{prefix}_{i:03d}.ppm", stretch=stretch)
+
+
+def save_mp4(
+    frames: Iterable[np.ndarray],
+    path: Path,
+    fps: int = 24,
+    stretch: bool = False,
+    macro_block_size: int = 1,
+) -> None:
+    """Save frames to MP4 if imageio is available."""
+    try:
+        import imageio
+        use_v3 = hasattr(imageio, "v3")
+    except Exception:
+        print("imageio is not available; skipping mp4 export.")
+        return
+    
+    path.parent.mkdir(parents=True, exist_ok=True)
+    prepared = []
+    for frame in frames:
+        rgb = _ensure_rgb(frame)
+        data = _normalize_to_uint8(rgb, stretch=stretch)
+        prepared.append(data)
+    
+    if use_v3:
+        imageio.v3.imwrite(path, prepared, fps=fps, macro_block_size=macro_block_size)
+    else:
+        imageio.mimsave(path, prepared, fps=fps, macro_block_size=macro_block_size)
+
+
+"""Small helpers for saving example outputs without extra deps."""

fractex/examples/architecture_pattern.py

@@ -0,0 +1,61 @@
+# Готические витражи
+import sys
+from pathlib import Path
+import argparse
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+EXAMPLES_DIR = Path(__file__).resolve().parent
+if str(EXAMPLES_DIR) not in sys.path:
+    sys.path.insert(0, str(EXAMPLES_DIR))
+
+from fractex.geometric_patterns_3d import (
+    CompositePatternGenerator3D,
+    GeometricPattern3D,
+    PatternParameters,
+)
+from _output import save_volume_slice
+from fractex.interactive import add_interactive_args, InteractiveConfig, run_interactive
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Architecture pattern example")
+    add_interactive_args(parser)
+    args = parser.parse_args()
+    stained_glass = CompositePatternGenerator3D(seed=42)
+    
+    gothic_pattern = stained_glass.generate_composite(
+        pattern_types=[
+            GeometricPattern3D.HONEYCOMB,
+            GeometricPattern3D.DIAMOND_STRUCTURE,
+            GeometricPattern3D.CRYSTAL_LATTICE,
+        ],
+        dimensions=(64, 64, 64),
+        params_list=[
+            PatternParameters(cell_size=0.2, wall_thickness=0.05),
+            PatternParameters(scale=2.0, thickness=0.03),
+            PatternParameters(crystal_type="cubic", scale=0.5, thickness=0.01),
+        ],
+    )
+    
+    print("Gothic pattern:", gothic_pattern.shape)
+    save_volume_slice(
+        gothic_pattern,
+        EXAMPLES_DIR / "output" / "architecture_pattern_slice.ppm",
+        stretch=True,
+    )
+    
+    if args.interactive:
+        config = InteractiveConfig.from_args(args, title="Architecture Pattern (interactive)")
+        depth = gothic_pattern.shape[0]
+        
+        def render_frame(t, w, h):
+            idx = int(abs(np.sin(t * 0.2)) * (depth - 1))
+            return gothic_pattern[idx, :, :, :3]
+        
+        run_interactive(render_frame, config)
+
+
+if __name__ == "__main__":
+    main()

fractex/examples/atmosphere.py

@@ -0,0 +1,54 @@
+# Динамическая атмосфера с изменяющимся временем дня
+import sys
+from pathlib import Path
+import math
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+
+class DynamicAtmosphere:
+    def __init__(self):
+        self.sun_direction = np.array([0.0, 1.0, 0.0])
+        self.sun_intensity = 1.0
+        self.scattering_coefficient = 0.1
+        self.phase_function_g = 0.7
+        self.sun_color = (1.0, 0.95, 0.9)
+    
+    def update_time_of_day(self, time_of_day: float):
+        # time_of_day: 0.0 (полночь) до 1.0 (полночь следующего дня)
+        sun_angle = time_of_day * 2 * math.pi
+        self.sun_direction = np.array([
+            math.sin(sun_angle),
+            math.cos(sun_angle),
+            0.0
+        ])
+        
+        # Цвет солнца
+        if 0.2 < time_of_day < 0.3:
+            self.sun_color = (1.0, 0.5, 0.3)
+        elif 0.7 < time_of_day < 0.8:
+            self.sun_color = (1.0, 0.4, 0.2)
+        else:
+            self.sun_color = (1.0, 0.95, 0.9)
+        
+        # Интенсивность
+        sun_height = self.sun_direction[1]
+        self.sun_intensity = max(0.1, sun_height * 2)
+        
+        # Параметры рассеяния
+        if time_of_day < 0.25 or time_of_day > 0.75:
+            self.scattering_coefficient = 0.03
+            self.phase_function_g = 0.3
+        else:
+            self.scattering_coefficient = 0.1
+            self.phase_function_g = 0.7
+
+
+if __name__ == "__main__":
+    atmosphere = DynamicAtmosphere()
+    for t in [0.0, 0.25, 0.5, 0.75]:
+        atmosphere.update_time_of_day(t)
+        print(f"time={t:.2f} sun_dir={atmosphere.sun_direction} intensity={atmosphere.sun_intensity:.2f}")

fractex/examples/composite_material.py

@@ -0,0 +1,63 @@
+# Создание сложных гибридных материалов
+import sys
+from pathlib import Path
+import argparse
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+EXAMPLES_DIR = Path(__file__).resolve().parent
+if str(EXAMPLES_DIR) not in sys.path:
+    sys.path.insert(0, str(EXAMPLES_DIR))
+
+from fractex.geometric_patterns_3d import (
+    CompositePatternGenerator3D,
+    GeometricPattern3D,
+    PatternParameters,
+)
+from _output import save_volume_slice
+from fractex.interactive import add_interactive_args, InteractiveConfig, run_interactive
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Composite material example")
+    add_interactive_args(parser)
+    args = parser.parse_args()
+    composite = CompositePatternGenerator3D(seed=42)
+    
+    # Кристаллическая основа с гироидными каналами
+    hybrid_material = composite.generate_composite(
+        pattern_types=[
+            GeometricPattern3D.CRYSTAL_LATTICE,
+            GeometricPattern3D.GYROID,
+            GeometricPattern3D.DIAMOND_STRUCTURE,
+        ],
+        dimensions=(64, 64, 64),
+        params_list=[
+            PatternParameters(crystal_type="diamond", thickness=0.05),
+            PatternParameters(scale=4.0, surface_threshold=0.2),
+            PatternParameters(scale=2.0, thickness=0.02),
+        ],
+        blend_mode="add",
+    )
+    
+    print("Hybrid material:", hybrid_material.shape)
+    save_volume_slice(
+        hybrid_material,
+        EXAMPLES_DIR / "output" / "composite_material_slice.ppm",
+        stretch=True,
+    )
+    
+    if args.interactive:
+        config = InteractiveConfig.from_args(args, title="Composite Material (interactive)")
+        depth = hybrid_material.shape[0]
+        
+        def render_frame(t, w, h):
+            idx = int(abs(np.sin(t * 0.2)) * (depth - 1))
+            return hybrid_material[idx, :, :, :3]
+        
+        run_interactive(render_frame, config)
+
+
+if __name__ == "__main__":
+    main()

fractex/examples/crystal_cave.py

@@ -0,0 +1,61 @@
+# Кристаллическая пещера
+import sys
+from pathlib import Path
+import argparse
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+EXAMPLES_DIR = Path(__file__).resolve().parent
+if str(EXAMPLES_DIR) not in sys.path:
+    sys.path.insert(0, str(EXAMPLES_DIR))
+
+from fractex.geometric_patterns_3d import (
+    CompositePatternGenerator3D,
+    GeometricPattern3D,
+    PatternParameters,
+)
+from _output import save_volume_slice
+from fractex.interactive import add_interactive_args, InteractiveConfig, run_interactive
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Crystal cave example")
+    add_interactive_args(parser)
+    args = parser.parse_args()
+    world_seed = 123
+    crystal_cave = CompositePatternGenerator3D(seed=world_seed)
+    
+    cave_pattern = crystal_cave.generate_layered_pattern(
+        pattern_layers=[
+            (GeometricPattern3D.CRYSTAL_LATTICE,
+             PatternParameters(crystal_type="hexagonal", scale=1.5), 0.8),
+            (GeometricPattern3D.DIAMOND_STRUCTURE,
+             PatternParameters(scale=3.0, thickness=0.02), 0.4),
+            (GeometricPattern3D.LAVA_LAMPS,
+             PatternParameters(surface_isolevel=0.3), 0.6),
+        ],
+        dimensions=(64, 64, 64),
+    )
+    
+    print("Cave pattern:", cave_pattern.shape)
+    save_volume_slice(
+        cave_pattern,
+        EXAMPLES_DIR / "output" / "crystal_cave_slice.ppm",
+        stretch=True,
+    )
+    
+    if args.interactive:
+        config = InteractiveConfig.from_args(args, title="Crystal Cave (interactive)")
+        depth = cave_pattern.shape[0]
+        
+        def render_frame(t, w, h):
+            idx = int(abs(np.sin(t * 0.2)) * (depth - 1))
+            return cave_pattern[idx, :, :, :3]
+        
+        run_interactive(render_frame, config)
+
+
+if __name__ == "__main__":
+    main()