Metadata-Version: 2.1
Name: Lab-3419
Version: 1.0.2
Summary: Lab_3419 is a cross-platform python library
Author-email: Subhendu Das <subhendudas.sinp@gmail.com>
License: MIT License
        
        Copyright (c) 2022 Subhendu Das
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

---

# Lab_3419

Lab_3419 is a cross-platform Python library that provides useful functions for MST simulation.

## Installation

To install Lab_3419, use the following command:

```
pip install Lab_3419
```

### Dependencies

Lab_3419 requires Python 3.6 or later. Before installing Lab_3419, make sure to install the numpy library:

```
pip install numpy
```

### Available functions

The code you provided includes several functions that perform different calculations and simulations. Here's a brief explanation of each function:

## 1. `add_resolusion(points_, res_=0.0)`

This function adds position resolution to the XY plane for the given set of 3D data points. It simulates the effect of measurement uncertainties or errors in the XY coordinates of the points. The function assumes that the Z coordinate remains fixed since it represents the position of the detector.

### Parameters:
- `points_`: A numpy array of shape (N, 3) representing the input 3D data points. Each row corresponds to a point, and the columns represent the X, Y, and Z coordinates respectively.
- `res_` (optional): The desired position resolution (standard deviation) to be added to the X and Y coordinates. It is specified in millimeters. The default value is 0.0, which means no additional resolution is added.

### Returns:
- `data_xyz_e_`: A numpy array of shape (N, 3) containing the modified 3D data points with added position resolution. The X and Y coordinates are randomly perturbed based on a normal distribution with a mean of 0 and a standard deviation of `res_`. The Z coordinate remains unchanged.

### Example Usage:
```python
import numpy as np

# Input data points
points = np.array([(1.0, 2.0, 3.0), (4.0, 5.0, 6.0), (7.0, 8.0, 9.0)])

# Adding position resolution with a standard deviation of 0.1 mm
resolution = 0.1
modified_points = add_resolusion(points, resolution)
```

In the above example, the function `add_resolusion()` is used to add position resolution to the input data points. The resulting modified points are stored in the `modified_points` variable.

Please note that the `add_resolusion()` function assumes that the input data points are provided in millimeters and returns the modified points in the same unit.


2. `find_angle(track_1, track_2)`: Calculates the angle between two tracks in 3D space using dot product and arccosine. Returns the angle in degrees.

3. `check_tracklets(points_)`: Checks the angles between various combinations of tracklets formed by points. Returns the maximum angle among them.


Certainly! Here's a detailed manual for the `fit_3D(points_)` function:

## 4. `fit_3D(points_)`

This function performs a linear regression on a set of 3D points to fit a straight line in 3D space. The regression is performed by fitting the x and y coordinates as a function of the z coordinate. The function assumes that the points lie approximately on a straight line and uses a linear model to estimate the parameters of the line.

### Parameters:
- `points_`: A numpy array of shape (N, 3) representing the input 3D points. Each row corresponds to a point, and the columns represent the X, Y, and Z coordinates respectively. The minimum required number of points is 2.

### Returns:
- `fit_xyz_`: A numpy array of shape (2, 3) containing the fitted line in 3D space. It consists of two points on the line, each represented by a triplet of X, Y, and Z coordinates.

### Example Usage:
```python
import numpy as np

# Simulated input points
simulated_points = np.array([(1.0, 2.0, 3.0), (4.0, 5.0, 6.0), (7.0, 8.0, 9.0)])

# Adding position resolution to the simulated points
position_resolution = 0.1
points = add_resolusion(points_=simulated_points, res_=position_resolution)

# Fitting a 3D line to the points
fitted_line = fit_3D(points)
```

In the above example, the function `fit_3D()` is used to fit a 3D line to the input points after adding position resolution. The resulting fitted line is stored in the `fitted_line` variable.

Please note that the `fit_3D()` function assumes that the input points are provided in millimeters and returns the fitted line in the same unit.

5. `fit_3D_with_parameters(points_)`: Fits a line to the given 3D points using polynomial regression. Returns the fitted line and regression parameters.

6. `POCA_Point(line_1_, line_2_)`: Calculates the Point of Closest Approach (POCA) and the angle between two lines in 3D space. Returns the POCA point and the angle in degrees.

Certainly! Here's a detailed manual for the `POCA_Point(line_1_, line_2_)` function:

## `POCA_Point(line_1_, line_2_)`

This function calculates the Point of Closest Approach (PoCA) between two lines in 3D space and also computes the angle between the two lines. It takes as input the fitted lines obtained from the `fit_3D()` function.

### Parameters:
- `line_1_`: A numpy array of shape (2, 3) representing the first fitted line in 3D space. It consists of two points on the line, each represented by a triplet of X, Y, and Z coordinates.
- `line_2_`: A numpy array of shape (2, 3) representing the second fitted line in 3D space. It follows the same format as `line_1_`.

### Returns:
- `poca_xyz`: A tuple of (X, Y, Z) representing the Point of Closest Approach (PoCA) between the two lines.
- `deviation`: The angle between the two lines in degrees.

### Example Usage:
```python
import numpy as np

# Example fitted lines
fitted_line_1 = np.array([(1.0, 2.0, 3.0), (4.0, 5.0, 6.0)])
fitted_line_2 = np.array([(7.0, 8.0, 9.0), (10.0, 11.0, 12.0)])

# Calculating the Point of Closest Approach (POCA) and deviation
poca_xyz, deviation = POCA_Point(fitted_line_1, fitted_line_2)
```

In the above example, the `POCA_Point()` function is used to calculate the Point of Closest Approach (POCA) between `fitted_line_1` and `fitted_line_2`. The resulting POCA point is stored in the `poca_xyz` variable, and the deviation (angle between the lines) is stored in the `deviation` variable.

Please note that the input lines `line_1_` and `line_2_` are expected to be in the same unit (e.g., millimeters) as they are obtained from the `fit_3D()` function. The returned POCA point (`poca_xyz`) is also in the same unit.

7. `POCA_Point_with_parameters(line_1_, line_2_)`: Calculates the POCA and angle between two lines in 3D space. Returns the POCA point, angle, and other POCA-related parameters.

8. `calculate(data_, sigma_=0.100)`: Parses input data, applies resolution, fits lines, and calculates the POCA point and angle. Returns the POCA point coordinates and angle in degrees.

9. `calculate_with_parameters(data_, sigma_=0.100)`: Similar to `calculate()`, but also returns the fitted line and regression parameters.

10. `file_to_poca(file_name_, is_save=False)`: Reads data from a file, performs the POCA calculation for each line, and optionally saves the results to a file. Returns an array of POCA points and angles.

11. `file_to_poca_mt(file_name_, is_save=False)`: Similar to `file_to_poca()`, but performs the calculations using multiple processes in parallel for improved performance.

12. `filter_poca_data(poca_data_, min_theta_)`: Filters the POCA data based on a minimum angle threshold. Returns the filtered data.

Please note that this is just an overview of the code's functionality. The exact usage and integration of these functions depend on your specific requirements and the data you're working with.

## Example Usage

Start by importing the Lab_3419 module:

```python
import Lab_3419 as lb
```

### Important Data Formats

Lab_3419 uses the following data formats:

1. A point in 3D Space: `point = (x, y, z)`
2. Line points in 3D Space: `points = numpy.array([(x1, y1, z1), (x2, y2, z2), (x3, y3, z3), ...])`
3. A fitted Line in 3D Space: `fitted_line = numpy.array([(x1, y1, z1), (x2, y2, z2)])`

### Fit 3D Line

To fit a 3D line, follow these steps:

```python
simulated_points = numpy.array([(x1, y1, z1), (x2, y2, z2), (x3, y3, z3)])
points = lb.add_resolution(points_=simulated_points, res_=position_resolution)
fitted_line = lb.fit_3D(points)
```

### Find POCA Point

To find the Point of Closest Approach (POCA) between two fitted lines, use the following code:

```python
poca_xyz, deviation = lb.POCA_Point(fitted_line_1, fitted_line_2)
```

### Find POCA Point Directly from Data String

If you have a data string containing multiple coordinates, you can calculate the POCA point directly using the following code:

```python
data_string = "x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4 x5 y5 z5 x6 y6 z6"
poca_x, poca_y, poca_z, deviation = lb.calculate(data_string)
```

### Find POCA Points Directly from Data File

If you have a data file containing multiple data strings, you can find the POCA points using the following code:

**Example Data File: data_file.txt**
```
-279.717 270.73 -391 -233.76 277.098 -321 -187.807 283.464 -251 140.424 328.94 249 186.895 335.379 319.776 232.346 341.674 389
42.0465 62.3473 -391 28.2942 59.1205 -321 14.5489 55.8892 -251 -83.7591 32.7117 249.426 -97.4228 29.4739 319 -111.175 26.2129 389
138.413 682.409 -391 134.046 628.646 -321 129.676 574.895 -251 98.4977 190.939 249 94.075 136.334 320.099 89.7752 83.4056 389
174.57 -20.909 -

391 149.972 -1.86935 -321 125.373 17.1698 -251 -50.315 153.155 249 -74.9115 172.191 319 -99.567 191.274 389
```

```python
all_poca_points = lb.file_to_poca("data_file.txt", is_save=False)
# To write into a new file, use "is_save=True".
# This will create a file named "data_file_poca_points.txt"

lb.file_to_poca("data_file.txt", is_save=True)  # Same function with multi-threaded mode
```

### Filter POCA Points According to Deviation Angle

Given a POCA data array and a minimum deviation angle, you can filter the POCA points using the following code:

**Example POCA File: data_file.txt**
```
-320.1396 -187.6816 -157.1030 1.0040
351.6875 -307.2162 -125.7960 0.0117
288.7207 349.4853 474.8601 3.0034
-41.1887 42.8014 32.7391 0.0243
```

```python
filter_poca_points = lb.filter_poca_data(poca_data_array, minimum_theta)
```

---
