img_phy_sim

  1"""
  2IPS: Image Physical Simulation Package
  3
  4This package provides a suite of tools for simulating, analyzing, and visualizing
  5rays (beams) in 2D images, along with general-purpose image and mathematical utilities.
  6It is designed for research workflows involving instance segmentation, ray tracing,
  7and image-based simulations, but can also be used in general image processing tasks.
  8
  9Submodules:
 10- `ray_tracing`<br>
 11    Tools for tracing rays through images with walls or obstacles,
 12    handling reflections, scaling, and visualization.<br>
 13    Key functionalities:
 14    - trace_beam / trace_beams
 15    - calc_reflection
 16    - get_wall_map
 17    - draw_rays
 18    - scale_rays
 19    - Utilities for merging rays, printing info, or getting pixel coordinates
 20
 21- `math`<br>
 22    Utilities for 2D geometry, coordinate transformations, and vector math.
 23    Provides functions for angle-to-vector conversions, normalization, and
 24    working with linear degree ranges.<br>
 25    Key functionalities:
 26    - degree_to_vector / vector_to_degree
 27    - get_linear_degree_range
 28    - normalize_point / denormalize_point
 29
 30- `img`<br>
 31    Image I/O, visualization, and analysis utilities.
 32    Includes functions for loading, saving, displaying, and annotating images,
 33    comparing predictions with ground truth, and plotting block-wise or line-wise
 34    statistics.<br>
 35    Key functionalities:
 36    - open / save
 37    - imshow / advanced_imshow / show_images / show_samples
 38    - plot_image_with_values / show_image_with_line_and_profile
 39    - get_width_height / get_bit_depth
 40
 41- `eval`<br>
 42    Accuracy measurement utilities.<br>
 43    Key functionalities:
 44    - calc_metrices
 45
 46- `data`<br>
 47    Loading utilities for PhysGen Dataset.<br>
 48    Key functionalities:
 49    - PhysGenDataset()
 50    - get_dataloader
 51    - save_dataset
 52
 53    
 54Typical workflow:
 551. Prepare an environment image using `img.open()` or generate it programmatically.
 562. Trace beams using `ray_tracing.trace_beams()` with specified start positions,
 57    directions, and wall values.
 583. Visualize the rays on images with `ray_tracing.draw_rays()`.
 594. Use `img` utilities for inspecting, annotating, or comparing images.
 605. Use `math` utilities for vector and angle calculations or normalization.
 61
 62Dependencies:
 63- numpy
 64- OpenCV (cv2)
 65- matplotlib
 66
 67Example:
 68```python
 69import img_phy_sim as ips
 70
 71# Load image
 72img = ips.img.open("scene.png")
 73
 74# Trace beams
 75rays = ips.ray_tracing.trace_beams(
 76    rel_position=(0.5, 0.5),
 77    img_src=img,
 78    directions_in_degree=[0, 45, 90, 135],
 79    wall_values=[0],
 80    wall_thickness=2,
 81    reflexion_order=2
 82)
 83
 84# Draw rays
 85output = ips.ray_tracing.draw_rays(rays, img_shape=img.shape, ray_value=255, ray_thickness=1)
 86
 87# Display result
 88ips.img.imshow(output, size=5)
 89```
 90
 91Or use ISM:
 92```python
 93# returns an 0.0-1.0 image
 94reflection_map = ips.ism.compute_reflection_map(
 95    source_rel=(0.5, 0.5),
 96    img=ips.img.open(input_src),
 97    wall_values=[0],   
 98    wall_thickness=1,
 99    max_order=1,
100    step_px=1,
101)
102
103img_in_255_range = ips.ism.reflection_map_to_img(reflection_map)
104
105ips.img.imshow(img_in_255_range, size=5)
106```
107
108Author:<br>
109Tobia Ippolito, 2026
110"""
111
112from . import img
113from . import ray_tracing
114from . import ism
115from . import math
116from . import eval
117from . import data
118# from . import data