Lab-3419 1.0.2

Lab_3419 is a cross-platform python library

---

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:

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:

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:

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:

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:

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:

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:

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

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

filter_poca_points = lb.filter_poca_data(poca_data_array, minimum_theta)

---