img-phy-sim 0.8__tar.gz → 1.0__tar.gz

{img_phy_sim-0.8 → img_phy_sim-1.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: img-phy-sim
-Version: 0.8
+Version: 1.0
 Summary: Physical Simulations on Images.
 Home-page: https://github.com/M-106/Image-Physics-Simulation
-Download-URL: https://github.com/M-106/Image-Physics-Simulation/archive/v_04.tar.gz
+Download-URL: https://github.com/M-106/Image-Physics-Simulation/archive/v_05.tar.gz
 Author: Tobia Ippolito
 Project-URL: Documentation, https://M-106.github.io/Image-Physics-Simulation/img_phy_sim
 Project-URL: Source, https://github.com/M-106/Image-Physics-Simulation
@@ -23,6 +23,7 @@ Requires-Dist: matplotlib
 Requires-Dist: scikit-image
 Requires-Dist: joblib
 Requires-Dist: shapely
+Requires-Dist: numba
 Provides-Extra: full
 Requires-Dist: torch; extra == "full"
 Requires-Dist: torchvision; extra == "full"
@@ -657,7 +658,100 @@ Short form:
 
 How to use which of them in `img-phy-sim`:
 
-FIXME
+Classical Ray-Tracing:
+```python
+# calc rays
+rays = ips.ray_tracing.trace_beams(rel_position=[0.5, 0.5], 
+                                   img_src=input_src, 
+                                   directions_in_degree=ips.math.get_linear_degree_range(start=0, stop=360, step_size=5),
+                                   wall_values=None, 
+                                   wall_thickness=1,
+                                   img_border_also_collide=False,
+                                   reflexion_order=3,
+                                   should_scale_rays=True,
+                                   should_scale_img=False)
+
+# show rays on input
+ray_img = ips.ray_tracing.draw_rays(rays, detail_draw=False, 
+                                    output_format="single_image", 
+                                    img_background=input_, ray_value=2, ray_thickness=1, 
+                                    img_shape=(256, 256), dtype=float, standard_value=0,
+                                    should_scale_rays_to_image=True, original_max_width=None, original_max_height=None,
+                                    show_only_reflections=True)
+ips.img.imshow(ray_img, size=4)
+```
+
+ISM:
+```python
+reflection_map = ips.ism.compute_reflection_map(
+    source_rel=(0.5, 0.5),
+    img=ips.img.open(input_src),
+    wall_values=[0],   
+    wall_thickness=1,
+    max_order=1,
+    step_px=1,
+    parallelization=-1
+)
+
+ips.img.imshow(ips.ism.reflection_map_to_img(reflection_map), size=5)
+```
+
+<br><br>
+
+Both formats are also available in a **iterative format**.
+
+
+Classical Ray-Tracing:
+```python
+rays_ = ips.ray_tracing.trace_beams(rel_position=[0.5, 0.5], 
+                                   img_src=img_src, 
+                                   directions_in_degree=[22, 56, 90, 146, 234, 285, 320],
+                                   wall_values=0.0, 
+                                   wall_thickness=0,
+                                   img_border_also_collide=False,
+                                   reflexion_order=2,
+                                   should_scale_rays=False,
+                                   should_scale_img=True,
+                                   iterative_tracking=True,    # IMPORTANT
+                                   iterative_steps=None        # IMPORTANT
+                                   )
+print("\nAccessing works the same, example Ray:", rays_[0][0][:min(len(rays_[0][0])-1, 3)])
+
+ray_imgs = ips.ray_tracing.draw_rays(rays_, detail_draw=False, 
+                                    output_format="single_image", 
+                                    img_background=img, ray_value=2, ray_thickness=1, 
+                                    img_shape=(256, 256), dtype=float, standard_value=0,
+                                    should_scale_rays_to_image=False, original_max_width=None, original_max_height=None)
 
+ips.img.advanced_imshow(ray_imgs[:10], title=None, image_width=4, axis=False,
+                        color_space="gray", cmap=None, cols=5, save_to=None,
+                        hspace=0.2, wspace=0.2,
+                        use_original_style=False, invert=False)
+```
+
+ISM:
+```python
+reflection_map_per_time = ips.ism.compute_reflection_map(
+    source_rel=(0.5, 0.5),
+    img=ips.img.open(input_src),
+    wall_values=[0],   
+    wall_thickness=1,
+    max_order=1,
+    step_px=1,
+    iterative_tracking=True,
+    iterative_steps=6,    # IMPORTANT
+    parallelization=-1    # IMPORTANT
+)
+
+ips.img.imshow(ips.ism.reflection_map_to_img(reflection_map_per_time[0]), size=5)
+
+len_ = len(reflection_map_per_time)
+ips.img.advanced_imshow([reflection_map_per_time[0], reflection_map_per_time[1], reflection_map_per_time[2],
+                         reflection_map_per_time[3], reflection_map_per_time[4], reflection_map_per_time[5]], 
+                        title=None, image_width=4, axis=False,
+                        color_space="gray", cmap=None, cols=3, save_to=None,
+                        hspace=0.2, wspace=0.2,
+                        use_original_style=False, invert=False)
+```
 
 

{img_phy_sim-0.8 → img_phy_sim-1.0}/README.md

@@ -615,7 +615,100 @@ Short form:
 
 How to use which of them in `img-phy-sim`:
 
-FIXME
+Classical Ray-Tracing:
+```python
+# calc rays
+rays = ips.ray_tracing.trace_beams(rel_position=[0.5, 0.5], 
+                                   img_src=input_src, 
+                                   directions_in_degree=ips.math.get_linear_degree_range(start=0, stop=360, step_size=5),
+                                   wall_values=None, 
+                                   wall_thickness=1,
+                                   img_border_also_collide=False,
+                                   reflexion_order=3,
+                                   should_scale_rays=True,
+                                   should_scale_img=False)
+
+# show rays on input
+ray_img = ips.ray_tracing.draw_rays(rays, detail_draw=False, 
+                                    output_format="single_image", 
+                                    img_background=input_, ray_value=2, ray_thickness=1, 
+                                    img_shape=(256, 256), dtype=float, standard_value=0,
+                                    should_scale_rays_to_image=True, original_max_width=None, original_max_height=None,
+                                    show_only_reflections=True)
+ips.img.imshow(ray_img, size=4)
+```
+
+ISM:
+```python
+reflection_map = ips.ism.compute_reflection_map(
+    source_rel=(0.5, 0.5),
+    img=ips.img.open(input_src),
+    wall_values=[0],   
+    wall_thickness=1,
+    max_order=1,
+    step_px=1,
+    parallelization=-1
+)
+
+ips.img.imshow(ips.ism.reflection_map_to_img(reflection_map), size=5)
+```
+
+<br><br>
+
+Both formats are also available in a **iterative format**.
+
+
+Classical Ray-Tracing:
+```python
+rays_ = ips.ray_tracing.trace_beams(rel_position=[0.5, 0.5], 
+                                   img_src=img_src, 
+                                   directions_in_degree=[22, 56, 90, 146, 234, 285, 320],
+                                   wall_values=0.0, 
+                                   wall_thickness=0,
+                                   img_border_also_collide=False,
+                                   reflexion_order=2,
+                                   should_scale_rays=False,
+                                   should_scale_img=True,
+                                   iterative_tracking=True,    # IMPORTANT
+                                   iterative_steps=None        # IMPORTANT
+                                   )
+print("\nAccessing works the same, example Ray:", rays_[0][0][:min(len(rays_[0][0])-1, 3)])
+
+ray_imgs = ips.ray_tracing.draw_rays(rays_, detail_draw=False, 
+                                    output_format="single_image", 
+                                    img_background=img, ray_value=2, ray_thickness=1, 
+                                    img_shape=(256, 256), dtype=float, standard_value=0,
+                                    should_scale_rays_to_image=False, original_max_width=None, original_max_height=None)
 
+ips.img.advanced_imshow(ray_imgs[:10], title=None, image_width=4, axis=False,
+                        color_space="gray", cmap=None, cols=5, save_to=None,
+                        hspace=0.2, wspace=0.2,
+                        use_original_style=False, invert=False)
+```
+
+ISM:
+```python
+reflection_map_per_time = ips.ism.compute_reflection_map(
+    source_rel=(0.5, 0.5),
+    img=ips.img.open(input_src),
+    wall_values=[0],   
+    wall_thickness=1,
+    max_order=1,
+    step_px=1,
+    iterative_tracking=True,
+    iterative_steps=6,    # IMPORTANT
+    parallelization=-1    # IMPORTANT
+)
+
+ips.img.imshow(ips.ism.reflection_map_to_img(reflection_map_per_time[0]), size=5)
+
+len_ = len(reflection_map_per_time)
+ips.img.advanced_imshow([reflection_map_per_time[0], reflection_map_per_time[1], reflection_map_per_time[2],
+                         reflection_map_per_time[3], reflection_map_per_time[4], reflection_map_per_time[5]], 
+                        title=None, image_width=4, axis=False,
+                        color_space="gray", cmap=None, cols=3, save_to=None,
+                        hspace=0.2, wspace=0.2,
+                        use_original_style=False, invert=False)
+```
 
 

{img_phy_sim-0.8 → img_phy_sim-1.0}/img_phy_sim/data.py

@@ -167,13 +167,13 @@ if DATA_DEPENDENCIES_AVAILABLE:
             Loads PhysGen Dataset.
 
             Parameters:
-            - variation : str
+            - variation : str <br>
                 Chooses the used dataset variant: sound_baseline, sound_reflection, sound_diffraction, sound_combined.
-            - mode : str
+            - mode : str <br>
                 Can be "train", "test", "eval".
-            - input_type : str
+            - input_type : str <br>
                 Defines the used Input -> "osm", "base_simulation"
-            - output_type : str
+            - output_type : str <br>
                 Defines the Output -> "standard", "complex_only"
             """
             self.device = 'cuda' if torch.cuda.is_available() else 'mps' if torch.backends.mps.is_available() else 'cpu'

{img_phy_sim-0.8 → img_phy_sim-1.0}/img_phy_sim/img.py

@@ -79,11 +79,13 @@ def get_bit_depth(img):
     Retrieve the bit depth of an image based on its NumPy data type.
 
     Parameters:
-        img (numpy.ndarray): Input image array.
+        img (numpy.ndarray): <br>
+            Input image array.
 
-    Returns:
-        int or str: Bit depth of the image (8, 16, 32, or 64).
-                    Returns "unknown" if the data type is not recognized.
+    Returns: <br>
+        int or str:<br> 
+            Bit depth of the image (8, 16, 32, or 64).<br>
+            Returns "unknown" if the data type is not recognized.
 
     Notes:
         The mapping is defined for common image dtypes:
@@ -108,10 +110,10 @@ def get_width_height(img, channels_before=0):
     Extract the width and height of an image, optionally offset by leading channels.
 
     Parameters:
-        img (numpy.ndarray): Input image array.
-        channels_before (int, optional): Offset in the shape dimension if
-                                         channels precede height and width
-                                         (default: 0).
+        - img (numpy.ndarray): <br>
+            Input image array.
+        - channels_before (int, optional): <br>
+            Offset in the shape dimension if channels precede height and width (default: 0).
 
     Returns:
         tuple: (width, height) of the image.
@@ -131,15 +133,16 @@ def open(src, should_scale=False, auto_scale_method=True, should_print=True, unc
     Load a grayscale image from a file path.
 
     Parameters:
-        src (str): Path to the image file.
-        should_scale (bool, optional): If True, scale pixel values to [0, 1]
-                                       according to bit depth (default: False).
-        auto_scale_method (bool, optionl): If True, the scaling will auto decide to up or down scale 
-                                            if should_sclae is also True else always down scale (default: True).
-        should_print (bool, optional): If True, print image info to console
-                                       (default: True).
-
-    Returns:
+        - src (str): Path to the image file.
+        - should_scale (bool, optional):<br>
+            If True, scale pixel values to [0, 1] according to bit depth (default: False).
+        - auto_scale_method (bool, optionl): <br>
+            If True, the scaling will auto decide to up or down scale 
+            if should_sclae is also True else always down scale (default: True).
+        - should_print (bool, optional): <br>
+            If True, print image info to console (default: True).
+
+    Returns: <br>
         numpy.ndarray: Loaded grayscale image.
 
     Example:
@@ -176,12 +179,14 @@ def save(img, src, should_scale=False, auto_scale_method=True):
     Save an image to disk.
 
     Parameters:
-        img (numpy.ndarray): Image to save.
-        src (str): Destination file path.
-        should_scale (bool, optional): If True, scale pixel values to [0, 1]
-                                       before saving (default: False).
-        auto_scale_method (bool, optionl): If True, the scaling will auto decide to up or down scale 
-                                            if should_sclae is also True else always down scale (default: True).
+        - img (numpy.ndarray): Image to save.
+        - src (str): <br>
+            Destination file path.
+        - should_scale (bool, optional): <br>
+            If True, scale pixel values to [0, 1] before saving (default: False).
+        - auto_scale_method (bool, optionl): <br>
+            If True, the scaling will auto decide to up or down scale 
+            if should_sclae is also True else always down scale (default: True).
 
     Notes:
         - The function uses OpenCV's `cv2.imwrite` for saving.
@@ -207,11 +212,14 @@ def imshow(img, size=8, axis_off=True, cmap="gray"):
     Display an image using Matplotlib.
 
     Parameters:
-        img (numpy.ndarray): Image to display.
-        size (int, optional): Display size in inches (default: 8).
-        axis_off (bool, optional): If True, hides the axes (default: True).
-        cmap (str, optional): Colormap name.
-                              Use 'random' for a random Matplotlib colormap (default: 'gray').
+        - img (numpy.ndarray): <br>
+            Image to display.
+        - size (int, optional): <br>
+            Display size in inches (default: 8).
+        - axis_off (bool, optional): <br>
+            If True, hides the axes (default: True).
+        - cmap (str, optional):<br>
+            Colormap name. Use 'random' for a random Matplotlib colormap (default: 'gray').
 
     Behavior:
         - If `img` has 3 channels, it is converted from BGR to RGB.
@@ -267,24 +275,39 @@ def show_samples(input_samples, pred_samples, real_samples, model_name="Model",
     It arranges them in a grid and can optionally normalize, invert, or save the output.
 
     Parameters:
-        input_samples (list[str] or list[np.ndarray]): Input sample images.
-        pred_samples (list[str] or list[np.ndarray]): Model prediction images.
-        real_samples (list[str] or list[np.ndarray]): Ground truth images.
-        model_name (str, optional): Name of the model to display in titles (default: "Model").
-        n_samples (int, optional): Number of sample groups to display (default: 3).
-        n_cols (int, optional): Number of columns per sample group (default: 4).
-                                Typically: Input | Prediction | Ground Truth | Difference.
-        image_width (int, optional): Width of one image in inches (default: 4).
-        cmap (str, optional): Colormap for displaying grayscale images (default: "gray").
-        normalize (bool, optional): Whether to normalize pixel values to [0, 1] (default: True).
-        invert (bool, optional): Whether to invert pixel values (255 - img) (default: False).
-        axis (bool, optional): Whether to show image axes (default: False).
-        save_to (str, optional): Path to save the figure (default: None).
-        hspace (float, optional): Vertical spacing between subplots (default: 0.3).
-        wspace (float, optional): Horizontal spacing between subplots (default: 0.2).
-        use_original_style (bool, optional): If True, preserves the current matplotlib style (default: False).
-
-    Returns:
+        - input_samples (list[str] or list[np.ndarray]): <br>
+            Input sample images.
+        - pred_samples (list[str] or list[np.ndarray]): <br>
+            Model prediction images.
+        - real_samples (list[str] or list[np.ndarray]): <br>
+            Ground truth images.
+        - model_name (str, optional): <br>
+            Name of the model to display in titles (default: "Model").
+        - n_samples (int, optional): <br>
+            Number of sample groups to display (default: 3).
+        - n_cols (int, optional): <br>
+            Number of columns per sample group (default: 4).<br>
+            Typically: Input | Prediction | Ground Truth | Difference.
+        - image_width (int, optional): <br>
+            Width of one image in inches (default: 4).
+        - cmap (str, optional): <br>
+            Colormap for displaying grayscale images (default: "gray").
+        - normalize (bool, optional): <br>
+            Whether to normalize pixel values to [0, 1] (default: True).
+        - invert (bool, optional): <br>
+            Whether to invert pixel values (255 - img) (default: False).
+        - axis (bool, optional):<br>
+            Whether to show image axes (default: False).
+        - save_to (str, optional): <br>
+            Path to save the figure (default: None).
+        - hspace (float, optional): <br>
+            Vertical spacing between subplots (default: 0.3).
+        - wspace (float, optional): <br>
+            Horizontal spacing between subplots (default: 0.2).
+        - use_original_style (bool, optional): <br>
+            If True, preserves the current matplotlib style (default: False).
+
+    Returns:<br>
         None
 
     Example:
@@ -364,22 +387,34 @@ def advanced_imshow(img, title=None, image_width=10, axis=False,
     input tensors, batch display, color inversion, and saving to disk.
 
     Parameters:
-        img (np.ndarray): Input image or batch of images.
-                          Accepted shapes:
-                              [H, W], [H, W, C], [N, H, W], or [N, H, W, C].
-        title (str or list[str], optional): Overall or per-image titles.
-        image_width (int, optional): Width of each image in inches (default: 10).
-        axis (bool, optional): Whether to show axes (default: False).
-        color_space (str, optional): Color space of the image: "RGB", "BGR", "gray", or "HSV" (default: "RGB").
-        cmap (str, optional): Matplotlib colormap for grayscale images (default: None).
-        cols (int, optional): Number of columns in the subplot grid (default: 1).
-        save_to (str, optional): File path to save the figure (default: None).
-        hspace (float, optional): Vertical spacing between subplots (default: 0.2).
-        wspace (float, optional): Horizontal spacing between subplots (default: 0.2).
-        use_original_style (bool, optional): Keep current Matplotlib style if True (default: False).
-        invert (bool, optional): Invert color values (default: False).
-
-    Returns:
+        - img (np.ndarray): <br>
+            Input image or batch of images.<br>
+            Accepted shapes:<br>
+            [H, W], [H, W, C], [N, H, W], or [N, H, W, C].
+        - title (str or list[str], optional): <br>
+            Overall or per-image titles.
+        - image_width (int, optional): <br>
+            Width of each image in inches (default: 10).
+        - axis (bool, optional): <br>
+            Whether to show axes (default: False).
+        - color_space (str, optional): <br>
+            Color space of the image: "RGB", "BGR", "gray", or "HSV" (default: "RGB").
+        - cmap (str, optional): <br>
+            Matplotlib colormap for grayscale images (default: None).
+        - cols (int, optional): <br>
+            Number of columns in the subplot grid (default: 1).
+        - save_to (str, optional): <br>
+            File path to save the figure (default: None).
+        - hspace (float, optional): <br>
+            Vertical spacing between subplots (default: 0.2).
+        - wspace (float, optional): <br>
+            Horizontal spacing between subplots (default: 0.2).
+        - use_original_style (bool, optional): <br>
+            Keep current Matplotlib style if True (default: False).
+        - invert (bool, optional): <br>
+            Invert color values (default: False).
+
+    Returns:<br>
         None
 
     Example:
@@ -468,19 +503,31 @@ def show_images(image_paths: list, title=None, image_width=5, axis=False,
     Load and display multiple images from disk using `advanced_imshow`.
 
     Parameters:
-        image_paths (list[str]): List of file paths to load.
-        title (str or list[str], optional): Plot title(s).
-        image_width (int, optional): Width of each image (default: 5).
-        axis (bool, optional): Whether to display axes (default: False).
-        color_space (str, optional): Color space to convert images to.
-                                     One of: "gray", "rgb", "hsv", "bgr" (default: "gray").
-        cmap (str, optional): Colormap for grayscale images (default: None).
-        cols (int, optional): Number of columns in the grid (default: 2).
-        save_to (str, optional): Path to save the figure (default: None).
-        hspace (float, optional): Vertical spacing between subplots (default: 0.01).
-        wspace (float, optional): Horizontal spacing between subplots (default: 0.01).
-        use_original_style (bool, optional): Keep current Matplotlib style (default: False).
-        invert (bool, optional): Whether to invert images (default: False).
+        - image_paths (list[str]): <br>
+            List of file paths to load.
+        - title (str or list[str], optional): <br>
+            Plot title(s).
+        - image_width (int, optional): <br>
+            Width of each image (default: 5).
+        - axis (bool, optional): <br>
+            Whether to display axes (default: False).
+        - color_space (str, optional): <br>
+            Color space to convert images to.<br>
+            One of: "gray", "rgb", "hsv", "bgr" (default: "gray").
+        - cmap (str, optional): <br>
+            Colormap for grayscale images (default: None).
+        - cols (int, optional): <br>
+            Number of columns in the grid (default: 2).
+        - save_to (str, optional): <br>
+            Path to save the figure (default: None).
+        - hspace (float, optional): <br>
+            Vertical spacing between subplots (default: 0.01).
+        - wspace (float, optional): <br>
+            Horizontal spacing between subplots (default: 0.01).
+        - use_original_style (bool, optional): <br>
+            Keep current Matplotlib style (default: False).
+        - invert (bool, optional): <br>
+            Whether to invert images (default: False).
 
     Returns:
         np.ndarray: Loaded images stacked as an array.
@@ -517,14 +564,20 @@ def plot_image_with_values(img, block_size=8, cmap='gray', title=None,
     values are displayed as text annotations directly on the image.
 
     Parameters:
-        img (np.ndarray): 2D grayscale image (H, W) or 3D single-channel image (H, W, 1).
-        block_size (int or tuple, optional): Size of each block (default: 8).
-        cmap (str, optional): Matplotlib colormap (default: "gray").
-        title (str, optional): Plot title (default: None).
-        font_size (int, optional): Font size of value annotations (default: 6).
-        save_to (str, optional): Path to save the figure (default: None).
-
-    Returns:
+        - img (np.ndarray): <br>
+            2D grayscale image (H, W) or 3D single-channel image (H, W, 1).
+        - block_size (int or tuple, optional): <br>
+            Size of each block (default: 8).
+        - cmap (str, optional): <br>
+            Matplotlib colormap (default: "gray").
+        - title (str, optional): <br>
+            Plot title (default: None).
+        - font_size (int, optional): <br>
+            Font size of value annotations (default: 6).
+        - save_to (str, optional): <br>
+            Path to save the figure (default: None).
+
+    Returns:<br>
         None
 
     Example:
@@ -596,14 +649,20 @@ def show_image_with_line_and_profile(imgs, axis='row', index=None, titles=None,
     and plot the corresponding pixel intensity profile below or beside each image.
 
     Parameters:
-        imgs (list[np.ndarray]): List of grayscale images to analyze.
-        axis (str, optional): Direction of the line ("row" or "column") (default: "row").
-        index (int, optional): Index of the selected line. If None, the central line is used (default: None).
-        titles (list[str], optional): Titles for each image (default: ["Image 1", "Image 2", ...]).
-        figsize (tuple, optional): Figure size per image pair (default: (10, 4)).
+        - imgs (list[np.ndarray]):<br>
+            List of grayscale images to analyze.
+        - axis (str, optional):<br>
+            Direction of the line ("row" or "column") (default: "row").
+        - index (int, optional): <br>
+            Index of the selected line. If None, the central line is used (default: None).
+        - titles (list[str], optional): <br>
+            Titles for each image (default: ["Image 1", "Image 2", ...]).
+        - figsize (tuple, optional): <br>
+            Figure size per image pair (default: (10, 4)).
 
     Returns:
-        list[np.ndarray]: List of pixel intensity profiles corresponding to the selected line in each image.
+        - list[np.ndarray]: <br>
+            List of pixel intensity profiles corresponding to the selected line in each image.
 
     Example:
         >>> show_image_with_line_and_profile(