Skip to content

odak.learn.tools

odak.learn.tools

Provides necessary definitions for general tools used across the library.

blur_gaussian(field, kernel_length=[21, 21], nsigma=[3, 3], padding='same')

A definition to blur a field using a Gaussian kernel.

Parameters:

  • field – 
            MxN field.
  • kernel_length (list, default: [21, 21] ) – 
            Length of the Gaussian kernel along X and Y axes.
  • nsigma – 
            Sigma of the Gaussian kernel along X and Y axes.
  • padding – 
            Padding value, see torch.nn.functional.conv2d() for more.

Returns:

  • blurred_field ( tensor ) –

    Blurred field.

Source code in odak/learn/tools/matrix.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
def blur_gaussian(field, kernel_length = [21, 21], nsigma = [3, 3], padding = 'same'):
    """
    A definition to blur a field using a Gaussian kernel.

    Parameters
    ----------
    field         : torch.tensor
                    MxN field.
    kernel_length : list
                    Length of the Gaussian kernel along X and Y axes.
    nsigma        : list
                    Sigma of the Gaussian kernel along X and Y axes.
    padding       : int or string
                    Padding value, see torch.nn.functional.conv2d() for more.

    Returns
    ----------
    blurred_field : torch.tensor
                    Blurred field.
    """
    kernel = generate_2d_gaussian(kernel_length, nsigma).to(field.device)
    kernel = kernel.unsqueeze(0).unsqueeze(0)
    if len(field.shape) == 2:
        field = field.view(1, 1, field.shape[-2], field.shape[-1])
    blurred_field = torch.nn.functional.conv2d(field, kernel, padding='same')
    if field.shape[1] == 1:
        blurred_field = blurred_field.view(
                                           blurred_field.shape[-2],
                                           blurred_field.shape[-1]
                                          )
    return blurred_field

center_of_triangle(triangle)

Definition to calculate center of a triangle.

Parameters:

  • triangle – 
            An array that contains three points defining a triangle (Mx3). It can also parallel process many triangles (NxMx3).
Source code in odak/raytracing/primitives.py 
73
74
75
76
77
78
79
80
81
82
83
84
85
def center_of_triangle(triangle):
    """
    Definition to calculate center of a triangle.

    Parameters
    ----------
    triangle      : ndarray
                    An array that contains three points defining a triangle (Mx3). It can also parallel process many triangles (NxMx3).
    """
    if len(triangle.shape) == 2:
        triangle = triangle.reshape((1, 3, 3))
    center = np.mean(triangle, axis=1)
    return center

circular_binary_mask(px, py, r)

Definition to generate a 2D circular binary mask.

Parameter

px : int Pixel count in x. py : int Pixel count in y. r : int Radius of the circle.

Returns:

  • mask ( tensor ) –

    Mask [1 x 1 x m x n].

Source code in odak/learn/tools/mask.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
def circular_binary_mask(px, py, r):
    """
    Definition to generate a 2D circular binary mask.

    Parameter
    ---------
    px           : int
                   Pixel count in x.
    py           : int
                   Pixel count in y.
    r            : int
                   Radius of the circle.

    Returns
    -------
    mask         : torch.tensor
                   Mask [1 x 1 x m x n].
    """
    x = torch.linspace(-px / 2., px / 2., px)
    y = torch.linspace(-py / 2., py / 2., py)
    X, Y = torch.meshgrid(x, y, indexing='ij')
    Z = (X ** 2 + Y ** 2) ** 0.5
    mask = torch.zeros_like(Z)
    mask[Z < r] = 1
    return mask

convolve2d(field, kernel)

Definition to convolve a field with a kernel by multiplying in frequency space.

Parameters:

  • field – 
          Input field with MxN shape.
  • kernel – 
          Input kernel with MxN shape.

Returns:

  • new_field ( tensor ) –

    Convolved field.

Source code in odak/learn/tools/matrix.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def convolve2d(field, kernel):
    """
    Definition to convolve a field with a kernel by multiplying in frequency space.

    Parameters
    ----------
    field       : torch.tensor
                  Input field with MxN shape.
    kernel      : torch.tensor
                  Input kernel with MxN shape.

    Returns
    ----------
    new_field   : torch.tensor
                  Convolved field.
    """
    fr = torch.fft.fft2(field)
    fr2 = torch.fft.fft2(torch.flip(torch.flip(kernel, [1, 0]), [0, 1]))
    m, n = fr.shape
    new_field = torch.real(torch.fft.ifft2(fr*fr2))
    new_field = torch.roll(new_field, shifts=(int(n/2+1), 0), dims=(1, 0))
    new_field = torch.roll(new_field, shifts=(int(m/2+1), 0), dims=(0, 1))
    return new_field

correlation_2d(first_tensor, second_tensor)

Definition to calculate the correlation between two tensors.

Parameters:

  • first_tensor – 
            First tensor.
  • second_tensor (tensor) – 
            Second tensor.

Returns:

  • correlation ( tensor ) –

    Correlation between the two tensors.

Source code in odak/learn/tools/matrix.py 
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
def correlation_2d(first_tensor, second_tensor):
    """
    Definition to calculate the correlation between two tensors.

    Parameters
    ----------
    first_tensor  : torch.tensor
                    First tensor.
    second_tensor : torch.tensor
                    Second tensor.

    Returns
    ----------
    correlation   : torch.tensor
                    Correlation between the two tensors.
    """
    fft_first_tensor = (torch.fft.fft2(first_tensor))
    fft_second_tensor = (torch.fft.fft2(second_tensor))
    conjugate_second_tensor = torch.conj(fft_second_tensor)
    result = torch.fft.ifftshift(torch.fft.ifft2(fft_first_tensor * conjugate_second_tensor))
    return result

crop_center(field, size=None)

Definition to crop the center of a field with 2Mx2N size. The outcome is a MxN array.

Parameters:

  • field – 
          Input field 2M x 2N or K x L x 2M x 2N or K x 2M x 2N x L array.
  • size – 
          Dimensions to crop with respect to center of the image (e.g., M x N or 1 x 1 x M x N).

Returns:

  • cropped ( ndarray ) –

    Cropped version of the input field.

Source code in odak/learn/tools/matrix.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def crop_center(field, size = None):
    """
    Definition to crop the center of a field with 2Mx2N size. The outcome is a MxN array.

    Parameters
    ----------
    field       : ndarray
                  Input field 2M x 2N or K x L x 2M x 2N or K x 2M x 2N x L array.
    size        : list
                  Dimensions to crop with respect to center of the image (e.g., M x N or 1 x 1 x M x N).

    Returns
    ----------
    cropped     : ndarray
                  Cropped version of the input field.
    """
    orig_resolution = field.shape
    if len(field.shape) < 3:
        field = field.unsqueeze(0)
    if len(field.shape) < 4:
        field = field.unsqueeze(0)
    permute_flag = False
    if field.shape[-1] < 5:
        permute_flag = True
        field = field.permute(0, 3, 1, 2)
    if type(size) == type(None):
        qx = int(field.shape[-2] // 4)
        qy = int(field.shape[-1] // 4)
        cropped_padded = field[:, :, qx: qx + field.shape[-2] // 2, qy:qy + field.shape[-1] // 2]
    else:
        cx = int(field.shape[-2] // 2)
        cy = int(field.shape[-1] // 2)
        hx = int(size[-2] // 2)
        hy = int(size[-1] // 2)
        cropped_padded = field[:, :, cx-hx:cx+hx, cy-hy:cy+hy]
    cropped = cropped_padded
    if permute_flag:
        cropped = cropped.permute(0, 2, 3, 1)
    if len(orig_resolution) == 2:
        cropped = cropped_padded.squeeze(0).squeeze(0)
    if len(orig_resolution) == 3:
        cropped = cropped_padded.squeeze(0)
    return cropped

cross_product(vector1, vector2)

Definition to cross product two vectors and return the resultant vector. Used method described under: http://en.wikipedia.org/wiki/Cross_product

Parameters:

  • vector1 – 
           A vector/ray.
  • vector2 – 
           A vector/ray.

Returns:

  • ray ( tensor ) –

    Array that contains starting points and cosines of a created ray.

Source code in odak/learn/tools/vector.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
def cross_product(vector1, vector2):
    """
    Definition to cross product two vectors and return the resultant vector. Used method described under: http://en.wikipedia.org/wiki/Cross_product

    Parameters
    ----------
    vector1      : torch.tensor
                   A vector/ray.
    vector2      : torch.tensor
                   A vector/ray.

    Returns
    ----------
    ray          : torch.tensor
                   Array that contains starting points and cosines of a created ray.
    """
    angle = torch.cross(vector1[1].T, vector2[1].T)
    angle = torch.tensor(angle)
    ray = torch.tensor([vector1[0], angle], dtype=torch.float32)
    return ray

distance_between_two_points(point1, point2)

Definition to calculate distance between two given points.

Parameters:

  • point1 – 
          First point in X,Y,Z.
  • point2 – 
          Second point in X,Y,Z.

Returns:

  • distance ( Tensor ) –

    Distance in between given two points.

Source code in odak/learn/tools/vector.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def distance_between_two_points(point1, point2):
    """
    Definition to calculate distance between two given points.

    Parameters
    ----------
    point1      : torch.Tensor
                  First point in X,Y,Z.
    point2      : torch.Tensor
                  Second point in X,Y,Z.

    Returns
    ----------
    distance    : torch.Tensor
                  Distance in between given two points.
    """
    point1 = torch.tensor(point1) if not isinstance(point1, torch.Tensor) else point1
    point2 = torch.tensor(point2) if not isinstance(point2, torch.Tensor) else point2

    if len(point1.shape) == 1 and len(point2.shape) == 1:
        distance = torch.sqrt(torch.sum((point1 - point2) ** 2))
    elif len(point1.shape) == 2 or len(point2.shape) == 2:
        distance = torch.sqrt(torch.sum((point1 - point2) ** 2, dim=-1))

    return distance

evaluate_3d_gaussians(points, centers=torch.zeros(1, 3), scales=torch.ones(1, 3), angles=torch.zeros(1, 3), opacity=torch.ones(1, 1))

Evaluate 3D Gaussian functions at given points, with optional rotation.

Parameters:

  • points – 
          The 3D points at which to evaluate the Gaussians.
  • centers – 
          The centers of the Gaussians.
  • scales – 
          The standard deviations (spread) of the Gaussians along each axis.
  • angles – 
          The rotation angles (in radians) for each Gaussian, applied to the points.
  • opacity – 
          Opacity of the Gaussians.

Returns:

  • intensities ( (Tensor, shape[n, 3]) ) –

    The evaluated Gaussian intensities at each point.

Source code in odak/learn/tools/function.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def evaluate_3d_gaussians(
                          points,
                          centers = torch.zeros(1, 3),
                          scales = torch.ones(1, 3),
                          angles = torch.zeros(1, 3),
                          opacity = torch.ones(1, 1),
                         ) -> torch.Tensor:
    """
    Evaluate 3D Gaussian functions at given points, with optional rotation.

    Parameters
    ----------
    points      : torch.Tensor, shape [n, 3]
                  The 3D points at which to evaluate the Gaussians.
    centers     : torch.Tensor, shape [n, 3]
                  The centers of the Gaussians.
    scales      : torch.Tensor, shape [n, 3]
                  The standard deviations (spread) of the Gaussians along each axis.
    angles      : torch.Tensor, shape [n, 3]
                  The rotation angles (in radians) for each Gaussian, applied to the points.
    opacity     : torch.Tensor, shape [n, 1]
                  Opacity of the Gaussians.

    Returns
    -------
    intensities : torch.Tensor, shape [n, 3]
                  The evaluated Gaussian intensities at each point.
    """
    points_rotated, _, _, _ = rotate_points(
                                            point = points,
                                            angles = angles,
                                            origin = centers
                                           )
    points_rotated = points_rotated - centers.unsqueeze(0)
    scales = scales.unsqueeze(0)
    exponent = torch.sum(-0.5 * (points_rotated / scales) ** 2, dim = -1)
    divider = (scales[:, :, 0] * scales[:, :, 1] * scales[:, :, 2]) * (2. * torch.pi) ** (3. / 2.)
    exponential = torch.exp(exponent)
    intensities = (exponential / divider)
    intensities = opacity.T * intensities
    return intensities

expanduser(filename)

Definition to decode filename using namespaces and shortcuts.

Parameters:

  • filename – 
            Filename.

Returns:

  • new_filename ( str ) –

    Filename.

Source code in odak/tools/file.py 
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
def expanduser(filename):
    """
    Definition to decode filename using namespaces and shortcuts.


    Parameters
    ----------
    filename      : str
                    Filename.


    Returns
    -------
    new_filename  : str
                    Filename.
    """
    new_filename = os.path.expanduser(filename)
    return new_filename

freeze(model)

A utility function to freeze the parameters of a provided model defined as a Pythonic class. For instance, odak.learn.models.unet is such a model.

Parameters:

  • model – 
             Model to be frozen, in other terms `requires_grad` to be set to `False`.
Source code in odak/learn/tools/models.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
def freeze(model):
    """
    A utility function to freeze the parameters of a provided model defined as a Pythonic class.
    For instance, `odak.learn.models.unet` is such a model.

    Parameters
    ----------
    model          : torch.nn.modules
                     Model to be frozen, in other terms `requires_grad` to be set to `False`.                    
    """
    for parameter in model.parameters():
        parameter.requires_grad = False

generate_2d_dirac_delta(kernel_length=[21, 21], a=[3, 3], mu=[0, 0], theta=0, normalize=False)

Generate 2D Dirac delta function by using Gaussian distribution. Inspired from https://en.wikipedia.org/wiki/Dirac_delta_function

Parameters:

  • kernel_length (list, default: [21, 21] ) – 
            Length of the Dirac delta function along X and Y axes.
  • a – 
            The scale factor in Gaussian distribution to approximate the Dirac delta function. 
        As a approaches zero, the Gaussian distribution becomes infinitely narrow and tall at the center (x=0), approaching the Dirac delta function.
  • mu – 
            Mu of the Gaussian kernel along X and Y axes.
  • theta – 
            The rotation angle of the 2D Dirac delta function.
  • normalize – 
            If set True, normalize the output.

Returns:

  • kernel_2d ( tensor ) –

    Generated 2D Dirac delta function.

Source code in odak/learn/tools/matrix.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
def generate_2d_dirac_delta(
                            kernel_length = [21, 21],
                            a = [3, 3],
                            mu = [0, 0],
                            theta = 0,
                            normalize = False
                           ):
    """
    Generate 2D Dirac delta function by using Gaussian distribution.
    Inspired from https://en.wikipedia.org/wiki/Dirac_delta_function

    Parameters
    ----------
    kernel_length : list
                    Length of the Dirac delta function along X and Y axes.
    a             : list
                    The scale factor in Gaussian distribution to approximate the Dirac delta function. 
                    As a approaches zero, the Gaussian distribution becomes infinitely narrow and tall at the center (x=0), approaching the Dirac delta function.
    mu            : list
                    Mu of the Gaussian kernel along X and Y axes.
    theta         : float
                    The rotation angle of the 2D Dirac delta function.
    normalize     : bool
                    If set True, normalize the output.

    Returns
    ----------
    kernel_2d     : torch.tensor
                    Generated 2D Dirac delta function.
    """
    x = torch.linspace(-kernel_length[0] / 2., kernel_length[0] / 2., kernel_length[0])
    y = torch.linspace(-kernel_length[1] / 2., kernel_length[1] / 2., kernel_length[1])
    X, Y = torch.meshgrid(x, y, indexing='ij')
    X = X - mu[0]
    Y = Y - mu[1]
    theta = torch.as_tensor(theta)
    X_rot = X * torch.cos(theta) - Y * torch.sin(theta)
    Y_rot = X * torch.sin(theta) + Y * torch.cos(theta)
    kernel_2d = (1 / (abs(a[0] * a[1]) * torch.pi)) * torch.exp(-((X_rot / a[0]) ** 2 + (Y_rot / a[1]) ** 2))
    if normalize:
        kernel_2d = kernel_2d / kernel_2d.max()
    return kernel_2d

generate_2d_gaussian(kernel_length=[21, 21], nsigma=[3, 3], mu=[0, 0], normalize=False)

Generate 2D Gaussian kernel. Inspired from https://stackoverflow.com/questions/29731726/how-to-calculate-a-gaussian-kernel-matrix-efficiently-in-numpy

Parameters:

  • kernel_length (list, default: [21, 21] ) – 
            Length of the Gaussian kernel along X and Y axes.
  • nsigma – 
            Sigma of the Gaussian kernel along X and Y axes.
  • mu – 
            Mu of the Gaussian kernel along X and Y axes.
  • normalize – 
            If set True, normalize the output.

Returns:

  • kernel_2d ( tensor ) –

    Generated Gaussian kernel.

Source code in odak/learn/tools/matrix.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def generate_2d_gaussian(kernel_length = [21, 21], nsigma = [3, 3], mu = [0, 0], normalize = False):
    """
    Generate 2D Gaussian kernel. Inspired from https://stackoverflow.com/questions/29731726/how-to-calculate-a-gaussian-kernel-matrix-efficiently-in-numpy

    Parameters
    ----------
    kernel_length : list
                    Length of the Gaussian kernel along X and Y axes.
    nsigma        : list
                    Sigma of the Gaussian kernel along X and Y axes.
    mu            : list
                    Mu of the Gaussian kernel along X and Y axes.
    normalize     : bool
                    If set True, normalize the output.

    Returns
    ----------
    kernel_2d     : torch.tensor
                    Generated Gaussian kernel.
    """
    x = torch.linspace(-kernel_length[0]/2., kernel_length[0]/2., kernel_length[0])
    y = torch.linspace(-kernel_length[1]/2., kernel_length[1]/2., kernel_length[1])
    X, Y = torch.meshgrid(x, y, indexing='ij')
    if nsigma[0] == 0:
        nsigma[0] = 1e-5
    if nsigma[1] == 0:
        nsigma[1] = 1e-5
    kernel_2d = 1. / (2. * torch.pi * nsigma[0] * nsigma[1]) * torch.exp(-((X - mu[0])**2. / (2. * nsigma[0]**2.) + (Y - mu[1])**2. / (2. * nsigma[1]**2.)))
    if normalize:
        kernel_2d = kernel_2d / kernel_2d.max()
    return kernel_2d

get_rotation_matrix(tilt_angles=[0.0, 0.0, 0.0], tilt_order='XYZ')

Function to generate rotation matrix for given tilt angles and tilt order.

Parameters:

  • tilt_angles – 
                 Tilt angles in degrees along XYZ axes.
  • tilt_order – 
                 Rotation order (e.g., XYZ, XZY, ZXY, YXZ, ZYX).

Returns:

  • rotmat ( tensor ) –

    Rotation matrix.

Source code in odak/learn/tools/transformation.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def get_rotation_matrix(tilt_angles = [0., 0., 0.], tilt_order = 'XYZ'):
    """
    Function to generate rotation matrix for given tilt angles and tilt order.


    Parameters
    ----------
    tilt_angles        : list
                         Tilt angles in degrees along XYZ axes.
    tilt_order         : str
                         Rotation order (e.g., XYZ, XZY, ZXY, YXZ, ZYX).

    Returns
    -------
    rotmat             : torch.tensor
                         Rotation matrix.
    """
    rotx = rotmatx(tilt_angles[0])
    roty = rotmaty(tilt_angles[1])
    rotz = rotmatz(tilt_angles[2])
    if tilt_order =='XYZ':
        rotmat = torch.mm(rotz,torch.mm(roty, rotx))
    elif tilt_order == 'XZY':
        rotmat = torch.mm(roty,torch.mm(rotz, rotx))
    elif tilt_order == 'ZXY':
        rotmat = torch.mm(roty,torch.mm(rotx, rotz))
    elif tilt_order == 'YXZ':
        rotmat = torch.mm(rotz,torch.mm(rotx, roty))
    elif tilt_order == 'ZYX':
         rotmat = torch.mm(rotx,torch.mm(roty, rotz))
    return rotmat

grid_sample(no=[10, 10], size=[100.0, 100.0], center=[0.0, 0.0, 0.0], angles=[0.0, 0.0, 0.0])

Definition to generate samples over a surface.

Parameters:

  • no – 
          Number of samples.
  • size – 
          Physical size of the surface.
  • center – 
          Center location of the surface.
  • angles – 
          Tilt of the surface.

Returns:

  • samples ( tensor ) –

    Samples generated.

  • rotx ( tensor ) –

    Rotation matrix at X axis.

  • roty ( tensor ) –

    Rotation matrix at Y axis.

  • rotz ( tensor ) –

    Rotation matrix at Z axis.

Source code in odak/learn/tools/sample.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def grid_sample(
                no = [10, 10],
                size = [100., 100.], 
                center = [0., 0., 0.], 
                angles = [0., 0., 0.]):
    """
    Definition to generate samples over a surface.

    Parameters
    ----------
    no          : list
                  Number of samples.
    size        : list
                  Physical size of the surface.
    center      : list
                  Center location of the surface.
    angles      : list
                  Tilt of the surface.

    Returns
    -------
    samples     : torch.tensor
                  Samples generated.
    rotx        : torch.tensor
                  Rotation matrix at X axis.
    roty        : torch.tensor
                  Rotation matrix at Y axis.
    rotz        : torch.tensor
                  Rotation matrix at Z axis.
    """
    center = torch.tensor(center)
    angles = torch.tensor(angles)
    size = torch.tensor(size)
    samples = torch.zeros((no[0], no[1], 3))
    x = torch.linspace(-size[0] / 2., size[0] / 2., no[0])
    y = torch.linspace(-size[1] / 2., size[1] / 2., no[1])
    X, Y = torch.meshgrid(x, y, indexing='ij')
    samples[:, :, 0] = X.detach().clone()
    samples[:, :, 1] = Y.detach().clone()
    samples = samples.reshape((samples.shape[0] * samples.shape[1], samples.shape[2]))
    samples, rotx, roty, rotz = rotate_points(samples, angles = angles, offset = center)
    return samples, rotx, roty, rotz

histogram_loss(frame, ground_truth, bins=32, limits=[0.0, 1.0])

Function for evaluating a frame against a target using histogram.

Parameters:

  • frame – 
               Input frame [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
  • ground_truth – 
               Ground truth [1 x 3 x m x n] or  [3 x m x n] or [1 x m x n] or  [m x n].
  • bins – 
               Number of bins.
  • limits – 
               Limits.

Returns:

  • loss ( float ) –

    Loss from evaluation.

Source code in odak/learn/tools/loss.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def histogram_loss(frame, ground_truth, bins = 32, limits = [0., 1.]):
    """
    Function for evaluating a frame against a target using histogram.

    Parameters
    ----------
    frame            : torch.tensor
                       Input frame [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
    ground_truth     : torch.tensor
                       Ground truth [1 x 3 x m x n] or  [3 x m x n] or [1 x m x n] or  [m x n].
    bins             : int
                       Number of bins.
    limits           : list
                       Limits.

    Returns
    -------
    loss             : float
                       Loss from evaluation.
    """
    if len(frame.shape) == 2:
        frame = frame.unsqueeze(0).unsqueeze(0)
    elif len(frame.shape) == 3:
        frame = frame.unsqueeze(0)

    if len(ground_truth.shape) == 2:
        ground_truth = ground_truth.unsqueeze(0).unsqueeze(0)
    elif len(ground_truth.shape) == 3:
        ground_truth = ground_truth.unsqueeze(0)

    histogram_frame = torch.zeros(frame.shape[1], bins).to(frame.device)
    histogram_ground_truth = torch.zeros(ground_truth.shape[1], bins).to(frame.device)

    l2 = torch.nn.MSELoss()

    for i in range(frame.shape[1]):
        histogram_frame[i] = torch.histc(frame[:, i].flatten(), bins=bins, min=limits[0], max=limits[1])
        histogram_ground_truth[i] = torch.histc(ground_truth[:, i].flatten(), bins=bins, min=limits[0], max=limits[1])

    loss = l2(histogram_frame, histogram_ground_truth)

    return loss

load_image(fn, normalizeby=0.0, torch_style=False)

Definition to load an image from a given location as a torch tensor.

Parameters:

  • fn – 
           Filename.
  • normalizeby – 
           Value to to normalize images with. Default value of zero will lead to no normalization.
  • torch_style – 
           If set True, it will load an image mxnx3 as 3xmxn.

Returns:

  • image ( ndarray ) –

    Image loaded as a Numpy array.

Source code in odak/learn/tools/file.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def load_image(fn, normalizeby = 0., torch_style = False):
    """
    Definition to load an image from a given location as a torch tensor.

    Parameters
    ----------
    fn           : str
                   Filename.
    normalizeby  : float or optional
                   Value to to normalize images with. Default value of zero will lead to no normalization.
    torch_style  : bool or optional
                   If set True, it will load an image mxnx3 as 3xmxn.

    Returns
    -------
    image        :  ndarray
                    Image loaded as a Numpy array.

    """
    image = odak.tools.load_image(fn, normalizeby = normalizeby, torch_style = torch_style)
    image = torch.from_numpy(image).float()
    return image

load_voxelized_PLY(ply_filename, voxel_size=[0.05, 0.05, 0.05], device=torch.device('cpu'))

Load a point cloud from a PLY file and convert it into a voxel grid representation.

Parameters:

  • ply_filename (str or Path) – 
           The path to the input PLY file containing triangle data.
  • voxel_size – 
           The size of each voxel in the x, y, and z directions. Default is [0.05, 0.05, 0.05].
  • device – 
           The device on which to perform computations. Default is CPU.

Returns:

  • points ( (Tensor, shape(N, 3)) ) –

    A tensor containing the coordinates of the voxel centers.

  • ground_truth ( (Tensor, shape(Gx * Gy * Gz)) ) –

    A binary tensor where each element indicates whether a corresponding voxel contains at least one point.

Notes
  • The function reads triangle data from the PLY file and computes the center points of these triangles.
  • These points are then processed to create a normalized point cloud, which is converted into a voxel grid.
  • Only voxels containing at least one point are marked as 1 in ground_truth.
  • All operations are performed on the specified device for efficiency.
Source code in odak/learn/tools/transformation.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
def load_voxelized_PLY(
                       ply_filename,
                       voxel_size = [0.05, 0.05, 0.05],
                       device = torch.device('cpu'),
                      ):
    """
    Load a point cloud from a PLY file and convert it into a voxel grid representation.

    Parameters
    ----------
    ply_filename : str or Path
                   The path to the input PLY file containing triangle data.
    voxel_size   : list or tuple, shape (3,), optional
                   The size of each voxel in the x, y, and z directions. Default is [0.05, 0.05, 0.05].
    device       : torch.device, optional
                   The device on which to perform computations. Default is CPU.

    Returns
    -------
    points      : torch.Tensor, shape (N, 3)
                  A tensor containing the coordinates of the voxel centers.
    ground_truth: torch.Tensor, shape (Gx * Gy * Gz,)
                  A binary tensor where each element indicates whether a corresponding voxel contains at least one point.

    Notes
    -----
    - The function reads triangle data from the PLY file and computes the center points of these triangles.
    - These points are then processed to create a normalized point cloud, which is converted into a voxel grid.
    - Only voxels containing at least one point are marked as 1 in `ground_truth`.
    - All operations are performed on the specified device for efficiency.
    """
    triangles = read_PLY(ply_filename)
    points = center_of_triangle(triangles)
    points = torch.as_tensor(points, device = device)
    points = points - points.mean()
    points = points / torch.amax(points)
    ground_truth = torch.ones(points.shape[0], device = device)
    voxel_locations, voxel_grid = point_cloud_to_voxel(points = points, voxel_size = voxel_size,)
    points = voxel_locations.reshape(-1, 3)
    ground_truth = voxel_grid.reshape(-1)
    return points, ground_truth

michelson_contrast(image, roi_high, roi_low)

A function to calculate michelson contrast ratio of given region of interests of the image.

Parameters:

  • image – 
            Image to be tested [1 x 3 x m x n] or [3 x m x n] or [m x n].
  • roi_high – 
            Corner locations of the roi for high intensity area [m_start, m_end, n_start, n_end].
  • roi_low – 
            Corner locations of the roi for low intensity area [m_start, m_end, n_start, n_end].

Returns:

  • result ( tensor ) –

    Michelson contrast for the given regions. [1] or [3] depending on input image.

Source code in odak/learn/tools/loss.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
def michelson_contrast(image, roi_high, roi_low):
    """
    A function to calculate michelson contrast ratio of given region of interests of the image.

    Parameters
    ----------
    image         : torch.tensor
                    Image to be tested [1 x 3 x m x n] or [3 x m x n] or [m x n].
    roi_high      : torch.tensor
                    Corner locations of the roi for high intensity area [m_start, m_end, n_start, n_end].
    roi_low       : torch.tensor
                    Corner locations of the roi for low intensity area [m_start, m_end, n_start, n_end].

    Returns
    -------
    result        : torch.tensor
                    Michelson contrast for the given regions. [1] or [3] depending on input image.
    """
    if len(image.shape) == 2:
        image = image.unsqueeze(0)
    if len(image.shape) == 3:
        image = image.unsqueeze(0)
    region_low = image[:, :, roi_low[0]:roi_low[1], roi_low[2]:roi_low[3]]
    region_high = image[:, :, roi_high[0]:roi_high[1], roi_high[2]:roi_high[3]]
    high = torch.mean(region_high, dim = (2, 3))
    low = torch.mean(region_low, dim = (2, 3))
    result = (high - low) / (high + low)
    return result.squeeze(0)

multi_scale_total_variation_loss(frame, levels=3)

Function for evaluating a frame against a target using multi scale total variation approach. Here, multi scale refers to image pyramid of an input frame, where at each level image resolution is half of the previous level.

Parameters:

  • frame – 
            Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].
  • levels – 
            Number of levels to go in the image pyriamid.

Returns:

  • loss ( float ) –

    Loss from evaluation.

Source code in odak/learn/tools/loss.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def multi_scale_total_variation_loss(frame, levels = 3):
    """
    Function for evaluating a frame against a target using multi scale total variation approach. Here, multi scale refers to image pyramid of an input frame, where at each level image resolution is half of the previous level.

    Parameters
    ----------
    frame         : torch.tensor
                    Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].
    levels        : int
                    Number of levels to go in the image pyriamid.

    Returns
    -------
    loss          : float
                    Loss from evaluation.
    """
    if len(frame.shape) == 2:
        frame = frame.unsqueeze(0)
    if len(frame.shape) == 3:
        frame = frame.unsqueeze(0)
    scale = torch.nn.Upsample(scale_factor = 0.5, mode = 'nearest')
    level = frame
    loss = 0
    for i in range(levels):
        if i != 0:
           level = scale(level)
        loss += total_variation_loss(level) 
    return loss

point_cloud_to_voxel(points, voxel_size=[0.1, 0.1, 0.1])

Convert a point cloud to a voxel grid representation.

Parameters:

  • points – 
         The input point cloud, where each row is a 3D point.
  • voxel_size ((list or Tensor, shape(3)), default: [0.1, 0.1, 0.1] ) – 
         The size of each voxel in the x, y, and z directions. Default is [0.1, 0.1, 0.1].

Returns:

  • locations ( (Tensor, shape(Gx, Gy, Gz, 3)) ) –

    The coordinates of each voxel center in the grid.

  • grid ( (Tensor, shape(Gx, Gy, Gz)) ) –

    A binary voxel grid where 1 indicates the presence of at least one point.

Notes
  • The voxel grid is constructed by discretizing the space between the minimum and maximum coordinates of the point cloud.
  • Only voxels containing at least one point are marked as 1.
  • The output grid is of type float32 and resides on the same device as the input points.
Source code in odak/learn/tools/transformation.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
def point_cloud_to_voxel(
                         points,
                         voxel_size = [0.1, 0.1, 0.1],
                        ):
    """
    Convert a point cloud to a voxel grid representation.

    Parameters
    ----------
    points     : torch.Tensor, shape (N, 3)
                 The input point cloud, where each row is a 3D point.
    voxel_size : list or torch.Tensor, shape (3,), optional
                 The size of each voxel in the x, y, and z directions. Default is [0.1, 0.1, 0.1].

    Returns
    -------
    locations  : torch.Tensor, shape (Gx, Gy, Gz, 3)
                 The coordinates of each voxel center in the grid.
    grid       : torch.Tensor, shape (Gx, Gy, Gz)
                 A binary voxel grid where 1 indicates the presence of at least one point.

    Notes
    -----
    - The voxel grid is constructed by discretizing the space between the minimum and maximum
      coordinates of the point cloud.
    - Only voxels containing at least one point are marked as 1.
    - The output grid is of type float32 and resides on the same device as the input points.
    """
    voxel_size = torch.as_tensor(voxel_size, device = points.device)

    min_coords = points.min(dim = 0).values
    max_coords = points.max(dim = 0).values
    grid_size = ((max_coords - min_coords) / voxel_size).ceil().int()
    points = points - min_coords

    x = torch.linspace(min_coords[0], max_coords[0], grid_size[0], device = points.device)
    y = torch.linspace(min_coords[1], max_coords[1], grid_size[1], device = points.device)
    z = torch.linspace(min_coords[2], max_coords[2], grid_size[2], device = points.device)
    X, Y, Z = torch.meshgrid(x, y, z, indexing='ij')
    locations = torch.stack([X, Y, Z], dim=-1)

    voxel_indices = (points / voxel_size).floor().int()
    mask = (voxel_indices >= 0).all(dim=1) & (voxel_indices < grid_size).all(dim=1)
    voxel_indices = voxel_indices[mask]
    grid = torch.zeros(grid_size.tolist(), dtype=torch.float32, device = points.device)
    grid[voxel_indices[:, 0], voxel_indices[:, 1], voxel_indices[:, 2]] = 1.

    return locations, grid

quantize(image_field, bits=8, limits=[0.0, 1.0])

Definition to quantize a image field (0-255, 8 bit) to a certain bits level.

Parameters:

  • image_field (tensor) – 
          Input image field between any range.
  • bits – 
          A value in between one to eight.
  • limits – 
          The minimum and maximum of the image_field variable.

Returns:

  • new_field ( tensor ) –

    Quantized image field.

Source code in odak/learn/tools/matrix.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
def quantize(image_field, bits = 8, limits = [0., 1.]):
    """ 
    Definition to quantize a image field (0-255, 8 bit) to a certain bits level.

    Parameters
    ----------
    image_field : torch.tensor
                  Input image field between any range.
    bits        : int
                  A value in between one to eight.
    limits      : list
                  The minimum and maximum of the image_field variable.

    Returns
    ----------
    new_field   : torch.tensor
                  Quantized image field.
    """
    normalized_field = (image_field - limits[0]) / (limits[1] - limits[0])
    divider = 2 ** bits
    new_field = normalized_field * divider
    new_field = new_field.int()
    return new_field

radial_basis_function(value, epsilon=0.5)

Function to pass a value into radial basis function with Gaussian description.

Parameters:

  • value – 
               Value(s) to pass to the radial basis function.
  • epsilon – 
               Epsilon used in the Gaussian radial basis function (e.g., y=e^(-(epsilon x value)^2).

Returns:

  • output ( tensor ) –

    Output values.

Source code in odak/learn/tools/loss.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def radial_basis_function(value, epsilon = 0.5):
    """
    Function to pass a value into radial basis function with Gaussian description.

    Parameters
    ----------
    value            : torch.tensor
                       Value(s) to pass to the radial basis function. 
    epsilon          : float
                       Epsilon used in the Gaussian radial basis function (e.g., y=e^(-(epsilon x value)^2).

    Returns
    -------
    output           : torch.tensor
                       Output values.
    """
    output = torch.exp((-(epsilon * value)**2))
    return output

read_PLY(fn, offset=[0, 0, 0], angles=[0.0, 0.0, 0.0], mode='XYZ')

Definition to read a PLY file and extract meshes from a given PLY file. Note that rotation is always with respect to 0,0,0.

Parameters:

  • fn – 
           Filename of a PLY file.
  • offset – 
           Offset in X,Y,Z.
  • angles – 
           Rotation angles in degrees.
  • mode – 
           Rotation mode determines ordering of the rotations at each axis. There are XYZ,YXZ,ZXY and ZYX modes.

Returns:

  • triangles ( ndarray ) –

    Triangles from a given PLY file. Note that the triangles coming out of this function isn't always structured in the right order and with the size of (MxN)x3. You can use numpy's reshape to restructure it to mxnx3 if you know what you are doing.

Source code in odak/tools/asset.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def read_PLY(fn, offset=[0, 0, 0], angles=[0., 0., 0.], mode='XYZ'):
    """
    Definition to read a PLY file and extract meshes from a given PLY file. Note that rotation is always with respect to 0,0,0.

    Parameters
    ----------
    fn           : string
                   Filename of a PLY file.
    offset       : ndarray
                   Offset in X,Y,Z.
    angles       : list
                   Rotation angles in degrees.
    mode         : str
                   Rotation mode determines ordering of the rotations at each axis. There are XYZ,YXZ,ZXY and ZYX modes. 

    Returns
    ----------
    triangles    : ndarray
                  Triangles from a given PLY file. Note that the triangles coming out of this function isn't always structured in the right order and with the size of (MxN)x3. You can use numpy's reshape to restructure it to mxnx3 if you know what you are doing.
    """
    if np.__name__ != 'numpy':
        import numpy as np_ply
    else:
        np_ply = np
    with open(fn, 'rb') as f:
        plydata = PlyData.read(f)
    triangle_ids = np_ply.vstack(plydata['face'].data['vertex_indices'])
    triangles = []
    for vertex_ids in triangle_ids:
        triangle = [
            rotate_point(plydata['vertex'][int(vertex_ids[0])
                                           ].tolist(), angles=angles, offset=offset)[0],
            rotate_point(plydata['vertex'][int(vertex_ids[1])
                                           ].tolist(), angles=angles, offset=offset)[0],
            rotate_point(plydata['vertex'][int(vertex_ids[2])
                                           ].tolist(), angles=angles, offset=offset)[0]
        ]
        triangle = np_ply.asarray(triangle)
        triangles.append(triangle)
    triangles = np_ply.array(triangles)
    triangles = np.asarray(triangles, dtype=np.float32)
    return triangles

resize(image, multiplier=0.5, mode='nearest')

Definition to resize an image.

Parameters:

  • image – 
            Image with MxNx3 resolution.
  • multiplier – 
            Multiplier used in resizing operation (e.g., 0.5 is half size in one axis).
  • mode – 
            Mode to be used in scaling, nearest, bilinear, etc.

Returns:

  • new_image ( tensor ) –

    Resized image.

Source code in odak/learn/tools/file.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def resize(image, multiplier = 0.5, mode = 'nearest'):
    """
    Definition to resize an image.

    Parameters
    ----------
    image         : torch.tensor
                    Image with MxNx3 resolution.
    multiplier    : float
                    Multiplier used in resizing operation (e.g., 0.5 is half size in one axis).
    mode          : str
                    Mode to be used in scaling, nearest, bilinear, etc.

    Returns
    -------
    new_image     : torch.tensor
                    Resized image.

    """
    scale = torch.nn.Upsample(scale_factor = multiplier, mode = mode)
    new_image = torch.zeros((int(image.shape[0] * multiplier), int(image.shape[1] * multiplier), 3)).to(image.device)
    for i in range(3):
        cache = image[:,:,i].unsqueeze(0)
        cache = cache.unsqueeze(0)
        new_cache = scale(cache).unsqueeze(0)
        new_image[:,:,i] = new_cache.unsqueeze(0)
    return new_image

rotate_points(point, angles=torch.zeros(1, 3), mode='XYZ', origin=torch.zeros(1, 3), offset=torch.zeros(1, 3))

Definition to rotate a given point. Note that rotation is always with respect to 0,0,0.

Parameters:

  • point – 
           A point with size of [3] or [1, 3] or [m, 3].
  • angles – 
           Rotation angles in degrees.
  • mode – 
           Rotation mode determines ordering of the rotations at each axis.
       There are XYZ,YXZ,ZXY and ZYX modes.
  • origin – 
           Reference point for a rotation.
       Expected size is [3] or [1, 3].
  • offset – 
           Shift with the given offset.
       Expected size is [3] or [1, 3] or [m, 3].

Returns:

  • result ( tensor ) –

    Result of the rotation [1 x 3] or [m x 3].

  • rotx ( tensor ) –

    Rotation matrix along X axis [3 x 3].

  • roty ( tensor ) –

    Rotation matrix along Y axis [3 x 3].

  • rotz ( tensor ) –

    Rotation matrix along Z axis [3 x 3].

Source code in odak/learn/tools/transformation.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def rotate_points(
                 point,
                 angles = torch.zeros(1, 3), 
                 mode = 'XYZ', 
                 origin = torch.zeros(1, 3), 
                 offset = torch.zeros(1, 3),
                ):
    """
    Definition to rotate a given point. Note that rotation is always with respect to 0,0,0.

    Parameters
    ----------
    point        : torch.tensor
                   A point with size of [3] or [1, 3] or [m, 3].
    angles       : torch.tensor
                   Rotation angles in degrees. 
    mode         : str
                   Rotation mode determines ordering of the rotations at each axis.
                   There are XYZ,YXZ,ZXY and ZYX modes.
    origin       : torch.tensor
                   Reference point for a rotation.
                   Expected size is [3] or [1, 3].
    offset       : torch.tensor
                   Shift with the given offset.
                   Expected size is [3] or [1, 3] or [m, 3].

    Returns
    ----------
    result       : torch.tensor
                   Result of the rotation [1 x 3] or [m x 3].
    rotx         : torch.tensor
                   Rotation matrix along X axis [3 x 3].
    roty         : torch.tensor
                   Rotation matrix along Y axis [3 x 3].
    rotz         : torch.tensor
                   Rotation matrix along Z axis [3 x 3].
    """
    origin = origin.to(point.device)
    offset = offset.to(point.device)
    angles = angles.to(point.device)

    if len(point.shape) == 1:
        point = point.unsqueeze(0)
    if len(angles.shape) == 1:
        angles = angles.unsqueeze(0)
    if len(origin.shape) == 1:
        origin = origin.unsqueeze(0)
    if len(offset.shape) == 1:
        offset = offset.unsqueeze(0)        

    rotx = rotmatx(angles[:, 0]).unsqueeze(0)
    roty = rotmaty(angles[:, 1]).unsqueeze(0)
    rotz = rotmatz(angles[:, 2]).unsqueeze(0)

    new_points = (point.unsqueeze(1) - origin.unsqueeze(0)).unsqueeze(-1)

    if mode == 'XYZ':
        result = (rotz @ (roty @ (rotx @ new_points)))
    elif mode == 'XZY':
        result = (roty @ (rotz @ (rotx @ new_points)))
    elif mode == 'YXZ':
        result = (rotz @ (rotx @ (roty @ new_points)))
    elif mode == 'ZXY':
        result = (roty @ (rotx @ (rotz @ new_points)))
    elif mode == 'ZYX':
        result = (rotx @ (roty @ (rotz @ new_points)))

    result = result.squeeze(-1)
    result = result + origin.unsqueeze(0) 
    result = result + offset.unsqueeze(0)
    if result.shape[1] == 1:
        result = result.squeeze(1)
    return result, rotx, roty, rotz

rotmatx(angle)

Definition to generate a rotation matrix along X axis.

Parameters:

  • angle – 
           Rotation angles in degrees.

Returns:

  • rotx ( tensor ) –

    Rotation matrix along X axis.

Source code in odak/learn/tools/transformation.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def rotmatx(angle):
    """
    Definition to generate a rotation matrix along X axis.

    Parameters
    ----------
    angle        : torch.tensor
                   Rotation angles in degrees.

    Returns
    ----------
    rotx         : torch.tensor
                   Rotation matrix along X axis.
    """
    angle = torch.deg2rad(angle)
    rotx = torch.zeros(angle.shape[0], 3, 3, device = angle.device)
    rotx[:, 0, 0] = 1.
    rotx[:, 1, 1] = torch.cos(angle)
    rotx[:, 1, 2] = - torch.sin(angle)
    rotx[:, 2, 1] = torch.sin(angle)
    rotx[:, 2, 2] = torch.cos(angle)
    if rotx.shape[0] == 1:
        rotx = rotx.squeeze(0)
    return rotx

rotmaty(angle)

Definition to generate a rotation matrix along Y axis.

Parameters:

  • angle – 
           Rotation angles in degrees.

Returns:

  • roty ( tensor ) –

    Rotation matrix along Y axis.

Source code in odak/learn/tools/transformation.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def rotmaty(angle):
    """
    Definition to generate a rotation matrix along Y axis.

    Parameters
    ----------
    angle        : torch.tensor
                   Rotation angles in degrees.

    Returns
    ----------
    roty         : torch.tensor
                   Rotation matrix along Y axis.
    """
    angle = torch.deg2rad(angle)
    roty = torch.zeros(angle.shape[0], 3, 3, device = angle.device)
    roty[:, 0, 0] = torch.cos(angle)
    roty[:, 0, 2] = torch.sin(angle)
    roty[:, 1, 1] = 1.
    roty[:, 2, 0] = - torch.sin(angle)
    roty[:, 2, 2] = torch.cos(angle)
    if roty.shape[0] == 1:
        roty = roty.squeeze(0)
    return roty

rotmatz(angle)

Definition to generate a rotation matrix along Z axis.

Parameters:

  • angle – 
           Rotation angles in degrees.

Returns:

  • rotz ( tensor ) –

    Rotation matrix along Z axis.

Source code in odak/learn/tools/transformation.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def rotmatz(angle):
    """
    Definition to generate a rotation matrix along Z axis.

    Parameters
    ----------
    angle        : torch.tensor
                   Rotation angles in degrees.

    Returns
    ----------
    rotz         : torch.tensor
                   Rotation matrix along Z axis.
    """
    angle = torch.deg2rad(angle)
    rotz = torch.zeros(angle.shape[0], 3, 3, device = angle.device)
    rotz[:, 0, 0] = torch.cos(angle)
    rotz[:, 0, 1] = - torch.sin(angle)
    rotz[:, 1, 0] = torch.sin(angle)
    rotz[:, 1, 1] = torch.cos(angle)
    rotz[:, 2, 2] = 1.
    if rotz.shape[0] == 1:
        rotz = rotz.squeeze(0)
    return rotz

same_side(p1, p2, a, b)

Definition to figure which side a point is on with respect to a line and a point. See http://www.blackpawn.com/texts/pointinpoly/ for more. If p1 and p2 are on the sameside, this definition returns True.

Parameters:

  • p1 – 
          Point(s) to check.
  • p2 – 
          This is the point check against.
  • a – 
          First point that forms the line.
  • b – 
          Second point that forms the line.
Source code in odak/learn/tools/vector.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def same_side(p1, p2, a, b):
    """
    Definition to figure which side a point is on with respect to a line and a point. See http://www.blackpawn.com/texts/pointinpoly/ for more. If p1 and p2 are on the sameside, this definition returns True.

    Parameters
    ----------
    p1          : list
                  Point(s) to check.
    p2          : list
                  This is the point check against.
    a           : list
                  First point that forms the line.
    b           : list
                  Second point that forms the line.
    """
    ba = torch.subtract(b, a)
    p1a = torch.subtract(p1, a)
    p2a = torch.subtract(p2, a)
    cp1 = torch.cross(ba, p1a)
    cp2 = torch.cross(ba, p2a)
    test = torch.dot(cp1, cp2)
    if len(p1.shape) > 1:
        return test >= 0
    if test >= 0:
        return True
    return False

save_image(fn, img, cmin=0, cmax=255, color_depth=8)

Definition to save a torch tensor as an image.

Parameters:

  • fn – 
           Filename.
  • img – 
           A numpy array with NxMx3 or NxMx1 shapes.
  • cmin – 
           Minimum value that will be interpreted as 0 level in the final image.
  • cmax – 
           Maximum value that will be interpreted as 255 level in the final image.
  • color_depth – 
           Color depth of an image. Default is eight.

Returns:

  • bool ( bool ) –

    True if successful.

Source code in odak/learn/tools/file.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def save_image(fn, img, cmin = 0, cmax = 255, color_depth = 8):
    """
    Definition to save a torch tensor as an image.

    Parameters
    ----------
    fn           : str
                   Filename.
    img          : ndarray
                   A numpy array with NxMx3 or NxMx1 shapes.
    cmin         : int
                   Minimum value that will be interpreted as 0 level in the final image.
    cmax         : int
                   Maximum value that will be interpreted as 255 level in the final image.
    color_depth  : int
                   Color depth of an image. Default is eight.


    Returns
    ----------
    bool         :  bool
                    True if successful.

    """
    if len(img.shape) ==  4:
        img = img.squeeze(0)
    if len(img.shape) > 2 and torch.argmin(torch.tensor(img.shape)) == 0:
        new_img = torch.zeros(img.shape[1], img.shape[2], img.shape[0]).to(img.device)
        for i in range(img.shape[0]):
            new_img[:, :, i] = img[i].detach().clone()
        img = new_img.detach().clone()
    img = img.cpu().detach().numpy()
    return odak.tools.save_image(fn, img, cmin = cmin, cmax = cmax, color_depth = color_depth)

save_torch_tensor(fn, tensor)

Definition to save a torch tensor.

Parameters:

  • fn – 
           Filename.
  • tensor – 
           Torch tensor to be saved.
Source code in odak/learn/tools/file.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def save_torch_tensor(fn, tensor):
    """
    Definition to save a torch tensor.


    Parameters
    ----------
    fn           : str
                   Filename.
    tensor       : torch.tensor
                   Torch tensor to be saved.
    """ 
    torch.save(tensor, expanduser(fn))

spatial_gradient(frame)

Function to calculate the spatial gradient of a given frame.

Parameters:

  • frame – 
            Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].

Returns:

  • diff_x ( float ) –

    Spatial gradient along X.

  • diff_y ( float ) –

    Spatial gradient along Y.

Source code in odak/learn/tools/loss.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def spatial_gradient(frame):
    """
    Function to calculate the spatial gradient of a given frame.

    Parameters
    ----------
    frame         : torch.tensor
                    Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].

    Returns
    -------
    diff_x        : float
                    Spatial gradient along X.
    diff_y        : float
                    Spatial gradient along Y.
    """
    if len(frame.shape) == 2:
        frame = frame.unsqueeze(0)
    if len(frame.shape) == 3:
        frame = frame.unsqueeze(0)    
    diff_x = frame[:, :, :, 1:] - frame[:, :, :, :-1]
    diff_y = frame[:, :, 1:, :] - frame[:, :, :-1, :]
    return diff_x, diff_y

tilt_towards(location, lookat)

Definition to tilt surface normal of a plane towards a point.

Parameters:

  • location – 
           Center of the plane to be tilted.
  • lookat – 
           Tilt towards this point.

Returns:

  • angles ( list ) –

    Rotation angles in degrees.

Source code in odak/learn/tools/transformation.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
def tilt_towards(location, lookat):
    """
    Definition to tilt surface normal of a plane towards a point.

    Parameters
    ----------
    location     : list
                   Center of the plane to be tilted.
    lookat       : list
                   Tilt towards this point.

    Returns
    ----------
    angles       : list
                   Rotation angles in degrees.
    """
    dx = location[0] - lookat[0]
    dy = location[1] - lookat[1]
    dz = location[2] - lookat[2]
    dist = torch.sqrt(torch.tensor(dx ** 2 + dy ** 2 + dz ** 2))
    phi = torch.atan2(torch.tensor(dy), torch.tensor(dx))
    theta = torch.arccos(dz / dist)
    angles = [0, float(torch.rad2deg(theta)), float(torch.rad2deg(phi))]
    return angles

torch_load(fn, weights_only=True)

Definition to load a torch files (*.pt).

Parameters:

  • fn – 
           Filename.
  • weights_only (bool, default: True ) – 
           See torch.load() for details.

Returns:

  • data ( any ) –

    See torch.load() for more.

Source code in odak/learn/tools/file.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def torch_load(fn, weights_only = True):
    """
    Definition to load a torch files (*.pt).

    Parameters
    ----------
    fn           : str
                   Filename.
    weights_only : bool
                   See torch.load() for details.

    Returns
    -------
    data         : any
                   See torch.load() for more.
    """  
    data = torch.load(
                      expanduser(fn),
                      weights_only = weights_only
                     )
    return data

total_variation_loss(frame)

Function for evaluating a frame against a target using total variation approach.

Parameters:

  • frame – 
            Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].

Returns:

  • loss ( float ) –

    Loss from evaluation.

Source code in odak/learn/tools/loss.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def total_variation_loss(frame):
    """
    Function for evaluating a frame against a target using total variation approach.

    Parameters
    ----------
    frame         : torch.tensor
                    Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].

    Returns
    -------
    loss          : float
                    Loss from evaluation.
    """
    if len(frame.shape) == 2:
        frame = frame.unsqueeze(0)
    if len(frame.shape) == 3:
        frame = frame.unsqueeze(0)
    diff_x, diff_y = spatial_gradient(frame)
    pixel_count = frame.shape[0] * frame.shape[1] * frame.shape[2] * frame.shape[3]
    loss = ((diff_x ** 2).sum() + (diff_y ** 2).sum()) / pixel_count
    return loss

unfreeze(model)

A utility function to unfreeze the parameters of a provided model defined as a Pythonic class. For instance, odak.learn.models.unet is such a model.

Parameters:

  • model – 
             Model to unfreeze, in other terms `requires_grad` to be set to `True`.
Source code in odak/learn/tools/models.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
def unfreeze(model):
    """
    A utility function to unfreeze the parameters of a provided model defined as a Pythonic class.
    For instance, `odak.learn.models.unet` is such a model.


    Parameters
    ----------
    model          : torch.nn.modules
                     Model to unfreeze, in other terms `requires_grad` to be set to `True`.
    """
    for parameter in model.parameters():
        parameter.requires_grad = True

weber_contrast(image, roi_high, roi_low)

A function to calculate weber contrast ratio of given region of interests of the image.

Parameters:

  • image – 
            Image to be tested [1 x 3 x m x n] or [3 x m x n] or [1 x m x n] or [m x n].
  • roi_high – 
            Corner locations of the roi for high intensity area [m_start, m_end, n_start, n_end].
  • roi_low – 
            Corner locations of the roi for low intensity area [m_start, m_end, n_start, n_end].

Returns:

  • result ( tensor ) –

    Weber contrast for given regions. [1] or [3] depending on input image.

Source code in odak/learn/tools/loss.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def weber_contrast(image, roi_high, roi_low):
    """
    A function to calculate weber contrast ratio of given region of interests of the image.

    Parameters
    ----------
    image         : torch.tensor
                    Image to be tested [1 x 3 x m x n] or [3 x m x n] or [1 x m x n] or [m x n].
    roi_high      : torch.tensor
                    Corner locations of the roi for high intensity area [m_start, m_end, n_start, n_end].
    roi_low       : torch.tensor
                    Corner locations of the roi for low intensity area [m_start, m_end, n_start, n_end].

    Returns
    -------
    result        : torch.tensor
                    Weber contrast for given regions. [1] or [3] depending on input image.
    """
    if len(image.shape) == 2:
        image = image.unsqueeze(0)
    if len(image.shape) == 3:
        image = image.unsqueeze(0)
    region_low = image[:, :, roi_low[0]:roi_low[1], roi_low[2]:roi_low[3]]
    region_high = image[:, :, roi_high[0]:roi_high[1], roi_high[2]:roi_high[3]]
    high = torch.mean(region_high, dim = (2, 3))
    low = torch.mean(region_low, dim = (2, 3))
    result = (high - low) / low
    return result.squeeze(0)

wrapped_mean_squared_error(image, ground_truth, reduction='mean')

A function to calculate the wrapped mean squared error between predicted and target angles.

Parameters:

  • image – 
            Image to be tested [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
  • ground_truth – 
            Ground truth to be tested [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
  • reduction – 
            Specifies the reduction to apply to the output: 'mean' (default) or 'sum'.

Returns:

  • wmse ( tensor ) –

    The calculated wrapped mean squared error.

Source code in odak/learn/tools/loss.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
def wrapped_mean_squared_error(image, ground_truth, reduction = 'mean'):
    """
    A function to calculate the wrapped mean squared error between predicted and target angles.

    Parameters
    ----------
    image         : torch.tensor
                    Image to be tested [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
    ground_truth  : torch.tensor
                    Ground truth to be tested [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
    reduction     : str
                    Specifies the reduction to apply to the output: 'mean' (default) or 'sum'.

    Returns
    -------
    wmse        : torch.tensor
                  The calculated wrapped mean squared error. 
    """
    sin_diff = torch.sin(image) - torch.sin(ground_truth)
    cos_diff = torch.cos(image) - torch.cos(ground_truth)
    loss = (sin_diff**2 + cos_diff**2)

    if reduction == 'mean':
        return loss.mean()
    elif reduction == 'sum':
        return loss.sum()
    else:
        raise ValueError("Invalid reduction type. Choose 'mean' or 'sum'.")

zernike_polynomial(n, m, rho, theta)

Compute the 2D Zernike polynomial Z_n^m(rho, theta).

Parameters:

  • n – 
         Radial degree of the polynomial (n >= 0).
  • m – 
         Azimuthal frequency of the polynomial.
  • rho – 
         Radial distance from the origin (0 to 1).
  • theta – 
         Azimuthal angle in radians. Shape (H, W).

Returns:

  • zernike ( Tensor ) –

    The computed 2D Zernike polynomial. Values are zero where rho > 1.

Source code in odak/learn/tools/function.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def zernike_polynomial(
                       n,
                       m,
                       rho,
                       theta,
                      ):
    """
    Compute the 2D Zernike polynomial Z_n^m(rho, theta).

    Parameters
    ----------
    n          : int
                 Radial degree of the polynomial (n >= 0).
    m          : int
                 Azimuthal frequency of the polynomial.
    rho        : torch.Tensor
                 Radial distance from the origin (0 to 1).
    theta      : torch.Tensor
                 Azimuthal angle in radians. Shape (H, W).


    Returns
    -------
    zernike    : torch.Tensor
                 The computed 2D Zernike polynomial.
                 Values are zero where rho > 1.
    """
    m_abs = abs(m)
    if m_abs > n or (n - m_abs) % 2 != 0:
        return torch.zeros(rho.shape, dtype=torch.complex64, device = rho.device)

    radial = torch.zeros_like(rho)

    for k in range((n - m_abs) // 2 + 1):
        num = ((-1) ** k * torch.exp(torch.lgamma(torch.tensor(n - k + 1.0))))
        den = (torch.exp(torch.lgamma(torch.tensor(k + 1.0))) *
               torch.exp(torch.lgamma(torch.tensor((n + m_abs) // 2 - k + 1.0))) *
               torch.exp(torch.lgamma(torch.tensor((n - m_abs) // 2 - k + 1.0))))
        radial += (num / den) * torch.pow(rho, n - 2 * k)

    if m >= 0:
        zernike = radial * torch.cos(m * theta)
    else:
        zernike = radial * torch.sin(m_abs * theta)
    zernike[rho > 1] = 0

    return zernike

zero_pad(field, size=None, method='center')

Definition to zero pad a MxN array to 2Mx2N array.

Parameters:

  • field – 
                Input field MxN or KxJxMxN or KxMxNxJ array.
  • size – 
                Size to be zeropadded (e.g., [m, n], last two dimensions only).
  • method – 
                Zeropad either by placing the content to center or to the left.

Returns:

  • field_zero_padded ( ndarray ) –

    Zeropadded version of the input field.

Source code in odak/learn/tools/matrix.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def zero_pad(field, size = None, method = 'center'):
    """
    Definition to zero pad a MxN array to 2Mx2N array.

    Parameters
    ----------
    field             : ndarray
                        Input field MxN or KxJxMxN or KxMxNxJ array.
    size              : list
                        Size to be zeropadded (e.g., [m, n], last two dimensions only).
    method            : str
                        Zeropad either by placing the content to center or to the left.

    Returns
    ----------
    field_zero_padded : ndarray
                        Zeropadded version of the input field.
    """
    orig_resolution = field.shape
    if len(field.shape) < 3:
        field = field.unsqueeze(0)
    if len(field.shape) < 4:
        field = field.unsqueeze(0)
    permute_flag = False
    if field.shape[-1] < 5:
        permute_flag = True
        field = field.permute(0, 3, 1, 2)
    if type(size) == type(None):
        resolution = [field.shape[0], field.shape[1], 2 * field.shape[-2], 2 * field.shape[-1]]
    else:
        resolution = [field.shape[0], field.shape[1], size[0], size[1]]
    field_zero_padded = torch.zeros(resolution, device = field.device, dtype = field.dtype)
    if method == 'center':
       start = [
                resolution[-2] // 2 - field.shape[-2] // 2,
                resolution[-1] // 2 - field.shape[-1] // 2
               ]
       field_zero_padded[
                         :, :,
                         start[0] : start[0] + field.shape[-2],
                         start[1] : start[1] + field.shape[-1]
                         ] = field
    elif method == 'left':
       field_zero_padded[
                         :, :,
                         0: field.shape[-2],
                         0: field.shape[-1]
                        ] = field
    if permute_flag == True:
        field_zero_padded = field_zero_padded.permute(0, 2, 3, 1)
    if len(orig_resolution) == 2:
        field_zero_padded = field_zero_padded.squeeze(0).squeeze(0)
    if len(orig_resolution) == 3:
        field_zero_padded = field_zero_padded.squeeze(0)
    return field_zero_padded

load_image(fn, normalizeby=0.0, torch_style=False)

Definition to load an image from a given location as a torch tensor.

Parameters:

  • fn – 
           Filename.
  • normalizeby – 
           Value to to normalize images with. Default value of zero will lead to no normalization.
  • torch_style – 
           If set True, it will load an image mxnx3 as 3xmxn.

Returns:

  • image ( ndarray ) –

    Image loaded as a Numpy array.

Source code in odak/learn/tools/file.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def load_image(fn, normalizeby = 0., torch_style = False):
    """
    Definition to load an image from a given location as a torch tensor.

    Parameters
    ----------
    fn           : str
                   Filename.
    normalizeby  : float or optional
                   Value to to normalize images with. Default value of zero will lead to no normalization.
    torch_style  : bool or optional
                   If set True, it will load an image mxnx3 as 3xmxn.

    Returns
    -------
    image        :  ndarray
                    Image loaded as a Numpy array.

    """
    image = odak.tools.load_image(fn, normalizeby = normalizeby, torch_style = torch_style)
    image = torch.from_numpy(image).float()
    return image

resize(image, multiplier=0.5, mode='nearest')

Definition to resize an image.

Parameters:

  • image – 
            Image with MxNx3 resolution.
  • multiplier – 
            Multiplier used in resizing operation (e.g., 0.5 is half size in one axis).
  • mode – 
            Mode to be used in scaling, nearest, bilinear, etc.

Returns:

  • new_image ( tensor ) –

    Resized image.

Source code in odak/learn/tools/file.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def resize(image, multiplier = 0.5, mode = 'nearest'):
    """
    Definition to resize an image.

    Parameters
    ----------
    image         : torch.tensor
                    Image with MxNx3 resolution.
    multiplier    : float
                    Multiplier used in resizing operation (e.g., 0.5 is half size in one axis).
    mode          : str
                    Mode to be used in scaling, nearest, bilinear, etc.

    Returns
    -------
    new_image     : torch.tensor
                    Resized image.

    """
    scale = torch.nn.Upsample(scale_factor = multiplier, mode = mode)
    new_image = torch.zeros((int(image.shape[0] * multiplier), int(image.shape[1] * multiplier), 3)).to(image.device)
    for i in range(3):
        cache = image[:,:,i].unsqueeze(0)
        cache = cache.unsqueeze(0)
        new_cache = scale(cache).unsqueeze(0)
        new_image[:,:,i] = new_cache.unsqueeze(0)
    return new_image

save_image(fn, img, cmin=0, cmax=255, color_depth=8)

Definition to save a torch tensor as an image.

Parameters:

  • fn – 
           Filename.
  • img – 
           A numpy array with NxMx3 or NxMx1 shapes.
  • cmin – 
           Minimum value that will be interpreted as 0 level in the final image.
  • cmax – 
           Maximum value that will be interpreted as 255 level in the final image.
  • color_depth – 
           Color depth of an image. Default is eight.

Returns:

  • bool ( bool ) –

    True if successful.

Source code in odak/learn/tools/file.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def save_image(fn, img, cmin = 0, cmax = 255, color_depth = 8):
    """
    Definition to save a torch tensor as an image.

    Parameters
    ----------
    fn           : str
                   Filename.
    img          : ndarray
                   A numpy array with NxMx3 or NxMx1 shapes.
    cmin         : int
                   Minimum value that will be interpreted as 0 level in the final image.
    cmax         : int
                   Maximum value that will be interpreted as 255 level in the final image.
    color_depth  : int
                   Color depth of an image. Default is eight.


    Returns
    ----------
    bool         :  bool
                    True if successful.

    """
    if len(img.shape) ==  4:
        img = img.squeeze(0)
    if len(img.shape) > 2 and torch.argmin(torch.tensor(img.shape)) == 0:
        new_img = torch.zeros(img.shape[1], img.shape[2], img.shape[0]).to(img.device)
        for i in range(img.shape[0]):
            new_img[:, :, i] = img[i].detach().clone()
        img = new_img.detach().clone()
    img = img.cpu().detach().numpy()
    return odak.tools.save_image(fn, img, cmin = cmin, cmax = cmax, color_depth = color_depth)

save_torch_tensor(fn, tensor)

Definition to save a torch tensor.

Parameters:

  • fn – 
           Filename.
  • tensor – 
           Torch tensor to be saved.
Source code in odak/learn/tools/file.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def save_torch_tensor(fn, tensor):
    """
    Definition to save a torch tensor.


    Parameters
    ----------
    fn           : str
                   Filename.
    tensor       : torch.tensor
                   Torch tensor to be saved.
    """ 
    torch.save(tensor, expanduser(fn))

torch_load(fn, weights_only=True)

Definition to load a torch files (*.pt).

Parameters:

  • fn – 
           Filename.
  • weights_only (bool, default: True ) – 
           See torch.load() for details.

Returns:

  • data ( any ) –

    See torch.load() for more.

Source code in odak/learn/tools/file.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def torch_load(fn, weights_only = True):
    """
    Definition to load a torch files (*.pt).

    Parameters
    ----------
    fn           : str
                   Filename.
    weights_only : bool
                   See torch.load() for details.

    Returns
    -------
    data         : any
                   See torch.load() for more.
    """  
    data = torch.load(
                      expanduser(fn),
                      weights_only = weights_only
                     )
    return data

histogram_loss(frame, ground_truth, bins=32, limits=[0.0, 1.0])

Function for evaluating a frame against a target using histogram.

Parameters:

  • frame – 
               Input frame [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
  • ground_truth – 
               Ground truth [1 x 3 x m x n] or  [3 x m x n] or [1 x m x n] or  [m x n].
  • bins – 
               Number of bins.
  • limits – 
               Limits.

Returns:

  • loss ( float ) –

    Loss from evaluation.

Source code in odak/learn/tools/loss.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def histogram_loss(frame, ground_truth, bins = 32, limits = [0., 1.]):
    """
    Function for evaluating a frame against a target using histogram.

    Parameters
    ----------
    frame            : torch.tensor
                       Input frame [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
    ground_truth     : torch.tensor
                       Ground truth [1 x 3 x m x n] or  [3 x m x n] or [1 x m x n] or  [m x n].
    bins             : int
                       Number of bins.
    limits           : list
                       Limits.

    Returns
    -------
    loss             : float
                       Loss from evaluation.
    """
    if len(frame.shape) == 2:
        frame = frame.unsqueeze(0).unsqueeze(0)
    elif len(frame.shape) == 3:
        frame = frame.unsqueeze(0)

    if len(ground_truth.shape) == 2:
        ground_truth = ground_truth.unsqueeze(0).unsqueeze(0)
    elif len(ground_truth.shape) == 3:
        ground_truth = ground_truth.unsqueeze(0)

    histogram_frame = torch.zeros(frame.shape[1], bins).to(frame.device)
    histogram_ground_truth = torch.zeros(ground_truth.shape[1], bins).to(frame.device)

    l2 = torch.nn.MSELoss()

    for i in range(frame.shape[1]):
        histogram_frame[i] = torch.histc(frame[:, i].flatten(), bins=bins, min=limits[0], max=limits[1])
        histogram_ground_truth[i] = torch.histc(ground_truth[:, i].flatten(), bins=bins, min=limits[0], max=limits[1])

    loss = l2(histogram_frame, histogram_ground_truth)

    return loss

michelson_contrast(image, roi_high, roi_low)

A function to calculate michelson contrast ratio of given region of interests of the image.

Parameters:

  • image – 
            Image to be tested [1 x 3 x m x n] or [3 x m x n] or [m x n].
  • roi_high – 
            Corner locations of the roi for high intensity area [m_start, m_end, n_start, n_end].
  • roi_low – 
            Corner locations of the roi for low intensity area [m_start, m_end, n_start, n_end].

Returns:

  • result ( tensor ) –

    Michelson contrast for the given regions. [1] or [3] depending on input image.

Source code in odak/learn/tools/loss.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
def michelson_contrast(image, roi_high, roi_low):
    """
    A function to calculate michelson contrast ratio of given region of interests of the image.

    Parameters
    ----------
    image         : torch.tensor
                    Image to be tested [1 x 3 x m x n] or [3 x m x n] or [m x n].
    roi_high      : torch.tensor
                    Corner locations of the roi for high intensity area [m_start, m_end, n_start, n_end].
    roi_low       : torch.tensor
                    Corner locations of the roi for low intensity area [m_start, m_end, n_start, n_end].

    Returns
    -------
    result        : torch.tensor
                    Michelson contrast for the given regions. [1] or [3] depending on input image.
    """
    if len(image.shape) == 2:
        image = image.unsqueeze(0)
    if len(image.shape) == 3:
        image = image.unsqueeze(0)
    region_low = image[:, :, roi_low[0]:roi_low[1], roi_low[2]:roi_low[3]]
    region_high = image[:, :, roi_high[0]:roi_high[1], roi_high[2]:roi_high[3]]
    high = torch.mean(region_high, dim = (2, 3))
    low = torch.mean(region_low, dim = (2, 3))
    result = (high - low) / (high + low)
    return result.squeeze(0)

multi_scale_total_variation_loss(frame, levels=3)

Function for evaluating a frame against a target using multi scale total variation approach. Here, multi scale refers to image pyramid of an input frame, where at each level image resolution is half of the previous level.

Parameters:

  • frame – 
            Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].
  • levels – 
            Number of levels to go in the image pyriamid.

Returns:

  • loss ( float ) –

    Loss from evaluation.

Source code in odak/learn/tools/loss.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def multi_scale_total_variation_loss(frame, levels = 3):
    """
    Function for evaluating a frame against a target using multi scale total variation approach. Here, multi scale refers to image pyramid of an input frame, where at each level image resolution is half of the previous level.

    Parameters
    ----------
    frame         : torch.tensor
                    Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].
    levels        : int
                    Number of levels to go in the image pyriamid.

    Returns
    -------
    loss          : float
                    Loss from evaluation.
    """
    if len(frame.shape) == 2:
        frame = frame.unsqueeze(0)
    if len(frame.shape) == 3:
        frame = frame.unsqueeze(0)
    scale = torch.nn.Upsample(scale_factor = 0.5, mode = 'nearest')
    level = frame
    loss = 0
    for i in range(levels):
        if i != 0:
           level = scale(level)
        loss += total_variation_loss(level) 
    return loss

radial_basis_function(value, epsilon=0.5)

Function to pass a value into radial basis function with Gaussian description.

Parameters:

  • value – 
               Value(s) to pass to the radial basis function.
  • epsilon – 
               Epsilon used in the Gaussian radial basis function (e.g., y=e^(-(epsilon x value)^2).

Returns:

  • output ( tensor ) –

    Output values.

Source code in odak/learn/tools/loss.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def radial_basis_function(value, epsilon = 0.5):
    """
    Function to pass a value into radial basis function with Gaussian description.

    Parameters
    ----------
    value            : torch.tensor
                       Value(s) to pass to the radial basis function. 
    epsilon          : float
                       Epsilon used in the Gaussian radial basis function (e.g., y=e^(-(epsilon x value)^2).

    Returns
    -------
    output           : torch.tensor
                       Output values.
    """
    output = torch.exp((-(epsilon * value)**2))
    return output

spatial_gradient(frame)

Function to calculate the spatial gradient of a given frame.

Parameters:

  • frame – 
            Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].

Returns:

  • diff_x ( float ) –

    Spatial gradient along X.

  • diff_y ( float ) –

    Spatial gradient along Y.

Source code in odak/learn/tools/loss.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def spatial_gradient(frame):
    """
    Function to calculate the spatial gradient of a given frame.

    Parameters
    ----------
    frame         : torch.tensor
                    Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].

    Returns
    -------
    diff_x        : float
                    Spatial gradient along X.
    diff_y        : float
                    Spatial gradient along Y.
    """
    if len(frame.shape) == 2:
        frame = frame.unsqueeze(0)
    if len(frame.shape) == 3:
        frame = frame.unsqueeze(0)    
    diff_x = frame[:, :, :, 1:] - frame[:, :, :, :-1]
    diff_y = frame[:, :, 1:, :] - frame[:, :, :-1, :]
    return diff_x, diff_y

total_variation_loss(frame)

Function for evaluating a frame against a target using total variation approach.

Parameters:

  • frame – 
            Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].

Returns:

  • loss ( float ) –

    Loss from evaluation.

Source code in odak/learn/tools/loss.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def total_variation_loss(frame):
    """
    Function for evaluating a frame against a target using total variation approach.

    Parameters
    ----------
    frame         : torch.tensor
                    Input frame [1 x 3 x m x n] or [3 x m x n] or [m x n].

    Returns
    -------
    loss          : float
                    Loss from evaluation.
    """
    if len(frame.shape) == 2:
        frame = frame.unsqueeze(0)
    if len(frame.shape) == 3:
        frame = frame.unsqueeze(0)
    diff_x, diff_y = spatial_gradient(frame)
    pixel_count = frame.shape[0] * frame.shape[1] * frame.shape[2] * frame.shape[3]
    loss = ((diff_x ** 2).sum() + (diff_y ** 2).sum()) / pixel_count
    return loss

weber_contrast(image, roi_high, roi_low)

A function to calculate weber contrast ratio of given region of interests of the image.

Parameters:

  • image – 
            Image to be tested [1 x 3 x m x n] or [3 x m x n] or [1 x m x n] or [m x n].
  • roi_high – 
            Corner locations of the roi for high intensity area [m_start, m_end, n_start, n_end].
  • roi_low – 
            Corner locations of the roi for low intensity area [m_start, m_end, n_start, n_end].

Returns:

  • result ( tensor ) –

    Weber contrast for given regions. [1] or [3] depending on input image.

Source code in odak/learn/tools/loss.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def weber_contrast(image, roi_high, roi_low):
    """
    A function to calculate weber contrast ratio of given region of interests of the image.

    Parameters
    ----------
    image         : torch.tensor
                    Image to be tested [1 x 3 x m x n] or [3 x m x n] or [1 x m x n] or [m x n].
    roi_high      : torch.tensor
                    Corner locations of the roi for high intensity area [m_start, m_end, n_start, n_end].
    roi_low       : torch.tensor
                    Corner locations of the roi for low intensity area [m_start, m_end, n_start, n_end].

    Returns
    -------
    result        : torch.tensor
                    Weber contrast for given regions. [1] or [3] depending on input image.
    """
    if len(image.shape) == 2:
        image = image.unsqueeze(0)
    if len(image.shape) == 3:
        image = image.unsqueeze(0)
    region_low = image[:, :, roi_low[0]:roi_low[1], roi_low[2]:roi_low[3]]
    region_high = image[:, :, roi_high[0]:roi_high[1], roi_high[2]:roi_high[3]]
    high = torch.mean(region_high, dim = (2, 3))
    low = torch.mean(region_low, dim = (2, 3))
    result = (high - low) / low
    return result.squeeze(0)

wrapped_mean_squared_error(image, ground_truth, reduction='mean')

A function to calculate the wrapped mean squared error between predicted and target angles.

Parameters:

  • image – 
            Image to be tested [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
  • ground_truth – 
            Ground truth to be tested [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
  • reduction – 
            Specifies the reduction to apply to the output: 'mean' (default) or 'sum'.

Returns:

  • wmse ( tensor ) –

    The calculated wrapped mean squared error.

Source code in odak/learn/tools/loss.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
def wrapped_mean_squared_error(image, ground_truth, reduction = 'mean'):
    """
    A function to calculate the wrapped mean squared error between predicted and target angles.

    Parameters
    ----------
    image         : torch.tensor
                    Image to be tested [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
    ground_truth  : torch.tensor
                    Ground truth to be tested [1 x 3 x m x n]  or [3 x m x n] or [1 x m x n] or [m x n].
    reduction     : str
                    Specifies the reduction to apply to the output: 'mean' (default) or 'sum'.

    Returns
    -------
    wmse        : torch.tensor
                  The calculated wrapped mean squared error. 
    """
    sin_diff = torch.sin(image) - torch.sin(ground_truth)
    cos_diff = torch.cos(image) - torch.cos(ground_truth)
    loss = (sin_diff**2 + cos_diff**2)

    if reduction == 'mean':
        return loss.mean()
    elif reduction == 'sum':
        return loss.sum()
    else:
        raise ValueError("Invalid reduction type. Choose 'mean' or 'sum'.")

blur_gaussian(field, kernel_length=[21, 21], nsigma=[3, 3], padding='same')

A definition to blur a field using a Gaussian kernel.

Parameters:

  • field – 
            MxN field.
  • kernel_length (list, default: [21, 21] ) – 
            Length of the Gaussian kernel along X and Y axes.
  • nsigma – 
            Sigma of the Gaussian kernel along X and Y axes.
  • padding – 
            Padding value, see torch.nn.functional.conv2d() for more.

Returns:

  • blurred_field ( tensor ) –

    Blurred field.

Source code in odak/learn/tools/matrix.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
def blur_gaussian(field, kernel_length = [21, 21], nsigma = [3, 3], padding = 'same'):
    """
    A definition to blur a field using a Gaussian kernel.

    Parameters
    ----------
    field         : torch.tensor
                    MxN field.
    kernel_length : list
                    Length of the Gaussian kernel along X and Y axes.
    nsigma        : list
                    Sigma of the Gaussian kernel along X and Y axes.
    padding       : int or string
                    Padding value, see torch.nn.functional.conv2d() for more.

    Returns
    ----------
    blurred_field : torch.tensor
                    Blurred field.
    """
    kernel = generate_2d_gaussian(kernel_length, nsigma).to(field.device)
    kernel = kernel.unsqueeze(0).unsqueeze(0)
    if len(field.shape) == 2:
        field = field.view(1, 1, field.shape[-2], field.shape[-1])
    blurred_field = torch.nn.functional.conv2d(field, kernel, padding='same')
    if field.shape[1] == 1:
        blurred_field = blurred_field.view(
                                           blurred_field.shape[-2],
                                           blurred_field.shape[-1]
                                          )
    return blurred_field

convolve2d(field, kernel)

Definition to convolve a field with a kernel by multiplying in frequency space.

Parameters:

  • field – 
          Input field with MxN shape.
  • kernel – 
          Input kernel with MxN shape.

Returns:

  • new_field ( tensor ) –

    Convolved field.

Source code in odak/learn/tools/matrix.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def convolve2d(field, kernel):
    """
    Definition to convolve a field with a kernel by multiplying in frequency space.

    Parameters
    ----------
    field       : torch.tensor
                  Input field with MxN shape.
    kernel      : torch.tensor
                  Input kernel with MxN shape.

    Returns
    ----------
    new_field   : torch.tensor
                  Convolved field.
    """
    fr = torch.fft.fft2(field)
    fr2 = torch.fft.fft2(torch.flip(torch.flip(kernel, [1, 0]), [0, 1]))
    m, n = fr.shape
    new_field = torch.real(torch.fft.ifft2(fr*fr2))
    new_field = torch.roll(new_field, shifts=(int(n/2+1), 0), dims=(1, 0))
    new_field = torch.roll(new_field, shifts=(int(m/2+1), 0), dims=(0, 1))
    return new_field

correlation_2d(first_tensor, second_tensor)

Definition to calculate the correlation between two tensors.

Parameters:

  • first_tensor – 
            First tensor.
  • second_tensor (tensor) – 
            Second tensor.

Returns:

  • correlation ( tensor ) –

    Correlation between the two tensors.

Source code in odak/learn/tools/matrix.py 
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
def correlation_2d(first_tensor, second_tensor):
    """
    Definition to calculate the correlation between two tensors.

    Parameters
    ----------
    first_tensor  : torch.tensor
                    First tensor.
    second_tensor : torch.tensor
                    Second tensor.

    Returns
    ----------
    correlation   : torch.tensor
                    Correlation between the two tensors.
    """
    fft_first_tensor = (torch.fft.fft2(first_tensor))
    fft_second_tensor = (torch.fft.fft2(second_tensor))
    conjugate_second_tensor = torch.conj(fft_second_tensor)
    result = torch.fft.ifftshift(torch.fft.ifft2(fft_first_tensor * conjugate_second_tensor))
    return result

crop_center(field, size=None)

Definition to crop the center of a field with 2Mx2N size. The outcome is a MxN array.

Parameters:

  • field – 
          Input field 2M x 2N or K x L x 2M x 2N or K x 2M x 2N x L array.
  • size – 
          Dimensions to crop with respect to center of the image (e.g., M x N or 1 x 1 x M x N).

Returns:

  • cropped ( ndarray ) –

    Cropped version of the input field.

Source code in odak/learn/tools/matrix.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def crop_center(field, size = None):
    """
    Definition to crop the center of a field with 2Mx2N size. The outcome is a MxN array.

    Parameters
    ----------
    field       : ndarray
                  Input field 2M x 2N or K x L x 2M x 2N or K x 2M x 2N x L array.
    size        : list
                  Dimensions to crop with respect to center of the image (e.g., M x N or 1 x 1 x M x N).

    Returns
    ----------
    cropped     : ndarray
                  Cropped version of the input field.
    """
    orig_resolution = field.shape
    if len(field.shape) < 3:
        field = field.unsqueeze(0)
    if len(field.shape) < 4:
        field = field.unsqueeze(0)
    permute_flag = False
    if field.shape[-1] < 5:
        permute_flag = True
        field = field.permute(0, 3, 1, 2)
    if type(size) == type(None):
        qx = int(field.shape[-2] // 4)
        qy = int(field.shape[-1] // 4)
        cropped_padded = field[:, :, qx: qx + field.shape[-2] // 2, qy:qy + field.shape[-1] // 2]
    else:
        cx = int(field.shape[-2] // 2)
        cy = int(field.shape[-1] // 2)
        hx = int(size[-2] // 2)
        hy = int(size[-1] // 2)
        cropped_padded = field[:, :, cx-hx:cx+hx, cy-hy:cy+hy]
    cropped = cropped_padded
    if permute_flag:
        cropped = cropped.permute(0, 2, 3, 1)
    if len(orig_resolution) == 2:
        cropped = cropped_padded.squeeze(0).squeeze(0)
    if len(orig_resolution) == 3:
        cropped = cropped_padded.squeeze(0)
    return cropped

generate_2d_dirac_delta(kernel_length=[21, 21], a=[3, 3], mu=[0, 0], theta=0, normalize=False)

Generate 2D Dirac delta function by using Gaussian distribution. Inspired from https://en.wikipedia.org/wiki/Dirac_delta_function

Parameters:

  • kernel_length (list, default: [21, 21] ) – 
            Length of the Dirac delta function along X and Y axes.
  • a – 
            The scale factor in Gaussian distribution to approximate the Dirac delta function. 
        As a approaches zero, the Gaussian distribution becomes infinitely narrow and tall at the center (x=0), approaching the Dirac delta function.
  • mu – 
            Mu of the Gaussian kernel along X and Y axes.
  • theta – 
            The rotation angle of the 2D Dirac delta function.
  • normalize – 
            If set True, normalize the output.

Returns:

  • kernel_2d ( tensor ) –

    Generated 2D Dirac delta function.

Source code in odak/learn/tools/matrix.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
def generate_2d_dirac_delta(
                            kernel_length = [21, 21],
                            a = [3, 3],
                            mu = [0, 0],
                            theta = 0,
                            normalize = False
                           ):
    """
    Generate 2D Dirac delta function by using Gaussian distribution.
    Inspired from https://en.wikipedia.org/wiki/Dirac_delta_function

    Parameters
    ----------
    kernel_length : list
                    Length of the Dirac delta function along X and Y axes.
    a             : list
                    The scale factor in Gaussian distribution to approximate the Dirac delta function. 
                    As a approaches zero, the Gaussian distribution becomes infinitely narrow and tall at the center (x=0), approaching the Dirac delta function.
    mu            : list
                    Mu of the Gaussian kernel along X and Y axes.
    theta         : float
                    The rotation angle of the 2D Dirac delta function.
    normalize     : bool
                    If set True, normalize the output.

    Returns
    ----------
    kernel_2d     : torch.tensor
                    Generated 2D Dirac delta function.
    """
    x = torch.linspace(-kernel_length[0] / 2., kernel_length[0] / 2., kernel_length[0])
    y = torch.linspace(-kernel_length[1] / 2., kernel_length[1] / 2., kernel_length[1])
    X, Y = torch.meshgrid(x, y, indexing='ij')
    X = X - mu[0]
    Y = Y - mu[1]
    theta = torch.as_tensor(theta)
    X_rot = X * torch.cos(theta) - Y * torch.sin(theta)
    Y_rot = X * torch.sin(theta) + Y * torch.cos(theta)
    kernel_2d = (1 / (abs(a[0] * a[1]) * torch.pi)) * torch.exp(-((X_rot / a[0]) ** 2 + (Y_rot / a[1]) ** 2))
    if normalize:
        kernel_2d = kernel_2d / kernel_2d.max()
    return kernel_2d

generate_2d_gaussian(kernel_length=[21, 21], nsigma=[3, 3], mu=[0, 0], normalize=False)

Generate 2D Gaussian kernel. Inspired from https://stackoverflow.com/questions/29731726/how-to-calculate-a-gaussian-kernel-matrix-efficiently-in-numpy

Parameters:

  • kernel_length (list, default: [21, 21] ) – 
            Length of the Gaussian kernel along X and Y axes.
  • nsigma – 
            Sigma of the Gaussian kernel along X and Y axes.
  • mu – 
            Mu of the Gaussian kernel along X and Y axes.
  • normalize – 
            If set True, normalize the output.

Returns:

  • kernel_2d ( tensor ) –

    Generated Gaussian kernel.

Source code in odak/learn/tools/matrix.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def generate_2d_gaussian(kernel_length = [21, 21], nsigma = [3, 3], mu = [0, 0], normalize = False):
    """
    Generate 2D Gaussian kernel. Inspired from https://stackoverflow.com/questions/29731726/how-to-calculate-a-gaussian-kernel-matrix-efficiently-in-numpy

    Parameters
    ----------
    kernel_length : list
                    Length of the Gaussian kernel along X and Y axes.
    nsigma        : list
                    Sigma of the Gaussian kernel along X and Y axes.
    mu            : list
                    Mu of the Gaussian kernel along X and Y axes.
    normalize     : bool
                    If set True, normalize the output.

    Returns
    ----------
    kernel_2d     : torch.tensor
                    Generated Gaussian kernel.
    """
    x = torch.linspace(-kernel_length[0]/2., kernel_length[0]/2., kernel_length[0])
    y = torch.linspace(-kernel_length[1]/2., kernel_length[1]/2., kernel_length[1])
    X, Y = torch.meshgrid(x, y, indexing='ij')
    if nsigma[0] == 0:
        nsigma[0] = 1e-5
    if nsigma[1] == 0:
        nsigma[1] = 1e-5
    kernel_2d = 1. / (2. * torch.pi * nsigma[0] * nsigma[1]) * torch.exp(-((X - mu[0])**2. / (2. * nsigma[0]**2.) + (Y - mu[1])**2. / (2. * nsigma[1]**2.)))
    if normalize:
        kernel_2d = kernel_2d / kernel_2d.max()
    return kernel_2d

quantize(image_field, bits=8, limits=[0.0, 1.0])

Definition to quantize a image field (0-255, 8 bit) to a certain bits level.

Parameters:

  • image_field (tensor) – 
          Input image field between any range.
  • bits – 
          A value in between one to eight.
  • limits – 
          The minimum and maximum of the image_field variable.

Returns:

  • new_field ( tensor ) –

    Quantized image field.

Source code in odak/learn/tools/matrix.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
def quantize(image_field, bits = 8, limits = [0., 1.]):
    """ 
    Definition to quantize a image field (0-255, 8 bit) to a certain bits level.

    Parameters
    ----------
    image_field : torch.tensor
                  Input image field between any range.
    bits        : int
                  A value in between one to eight.
    limits      : list
                  The minimum and maximum of the image_field variable.

    Returns
    ----------
    new_field   : torch.tensor
                  Quantized image field.
    """
    normalized_field = (image_field - limits[0]) / (limits[1] - limits[0])
    divider = 2 ** bits
    new_field = normalized_field * divider
    new_field = new_field.int()
    return new_field

zero_pad(field, size=None, method='center')

Definition to zero pad a MxN array to 2Mx2N array.

Parameters:

  • field – 
                Input field MxN or KxJxMxN or KxMxNxJ array.
  • size – 
                Size to be zeropadded (e.g., [m, n], last two dimensions only).
  • method – 
                Zeropad either by placing the content to center or to the left.

Returns:

  • field_zero_padded ( ndarray ) –

    Zeropadded version of the input field.

Source code in odak/learn/tools/matrix.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def zero_pad(field, size = None, method = 'center'):
    """
    Definition to zero pad a MxN array to 2Mx2N array.

    Parameters
    ----------
    field             : ndarray
                        Input field MxN or KxJxMxN or KxMxNxJ array.
    size              : list
                        Size to be zeropadded (e.g., [m, n], last two dimensions only).
    method            : str
                        Zeropad either by placing the content to center or to the left.

    Returns
    ----------
    field_zero_padded : ndarray
                        Zeropadded version of the input field.
    """
    orig_resolution = field.shape
    if len(field.shape) < 3:
        field = field.unsqueeze(0)
    if len(field.shape) < 4:
        field = field.unsqueeze(0)
    permute_flag = False
    if field.shape[-1] < 5:
        permute_flag = True
        field = field.permute(0, 3, 1, 2)
    if type(size) == type(None):
        resolution = [field.shape[0], field.shape[1], 2 * field.shape[-2], 2 * field.shape[-1]]
    else:
        resolution = [field.shape[0], field.shape[1], size[0], size[1]]
    field_zero_padded = torch.zeros(resolution, device = field.device, dtype = field.dtype)
    if method == 'center':
       start = [
                resolution[-2] // 2 - field.shape[-2] // 2,
                resolution[-1] // 2 - field.shape[-1] // 2
               ]
       field_zero_padded[
                         :, :,
                         start[0] : start[0] + field.shape[-2],
                         start[1] : start[1] + field.shape[-1]
                         ] = field
    elif method == 'left':
       field_zero_padded[
                         :, :,
                         0: field.shape[-2],
                         0: field.shape[-1]
                        ] = field
    if permute_flag == True:
        field_zero_padded = field_zero_padded.permute(0, 2, 3, 1)
    if len(orig_resolution) == 2:
        field_zero_padded = field_zero_padded.squeeze(0).squeeze(0)
    if len(orig_resolution) == 3:
        field_zero_padded = field_zero_padded.squeeze(0)
    return field_zero_padded

grid_sample(no=[10, 10], size=[100.0, 100.0], center=[0.0, 0.0, 0.0], angles=[0.0, 0.0, 0.0])

Definition to generate samples over a surface.

Parameters:

  • no – 
          Number of samples.
  • size – 
          Physical size of the surface.
  • center – 
          Center location of the surface.
  • angles – 
          Tilt of the surface.

Returns:

  • samples ( tensor ) –

    Samples generated.

  • rotx ( tensor ) –

    Rotation matrix at X axis.

  • roty ( tensor ) –

    Rotation matrix at Y axis.

  • rotz ( tensor ) –

    Rotation matrix at Z axis.

Source code in odak/learn/tools/sample.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def grid_sample(
                no = [10, 10],
                size = [100., 100.], 
                center = [0., 0., 0.], 
                angles = [0., 0., 0.]):
    """
    Definition to generate samples over a surface.

    Parameters
    ----------
    no          : list
                  Number of samples.
    size        : list
                  Physical size of the surface.
    center      : list
                  Center location of the surface.
    angles      : list
                  Tilt of the surface.

    Returns
    -------
    samples     : torch.tensor
                  Samples generated.
    rotx        : torch.tensor
                  Rotation matrix at X axis.
    roty        : torch.tensor
                  Rotation matrix at Y axis.
    rotz        : torch.tensor
                  Rotation matrix at Z axis.
    """
    center = torch.tensor(center)
    angles = torch.tensor(angles)
    size = torch.tensor(size)
    samples = torch.zeros((no[0], no[1], 3))
    x = torch.linspace(-size[0] / 2., size[0] / 2., no[0])
    y = torch.linspace(-size[1] / 2., size[1] / 2., no[1])
    X, Y = torch.meshgrid(x, y, indexing='ij')
    samples[:, :, 0] = X.detach().clone()
    samples[:, :, 1] = Y.detach().clone()
    samples = samples.reshape((samples.shape[0] * samples.shape[1], samples.shape[2]))
    samples, rotx, roty, rotz = rotate_points(samples, angles = angles, offset = center)
    return samples, rotx, roty, rotz

get_rotation_matrix(tilt_angles=[0.0, 0.0, 0.0], tilt_order='XYZ')

Function to generate rotation matrix for given tilt angles and tilt order.

Parameters:

  • tilt_angles – 
                 Tilt angles in degrees along XYZ axes.
  • tilt_order – 
                 Rotation order (e.g., XYZ, XZY, ZXY, YXZ, ZYX).

Returns:

  • rotmat ( tensor ) –

    Rotation matrix.

Source code in odak/learn/tools/transformation.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def get_rotation_matrix(tilt_angles = [0., 0., 0.], tilt_order = 'XYZ'):
    """
    Function to generate rotation matrix for given tilt angles and tilt order.


    Parameters
    ----------
    tilt_angles        : list
                         Tilt angles in degrees along XYZ axes.
    tilt_order         : str
                         Rotation order (e.g., XYZ, XZY, ZXY, YXZ, ZYX).

    Returns
    -------
    rotmat             : torch.tensor
                         Rotation matrix.
    """
    rotx = rotmatx(tilt_angles[0])
    roty = rotmaty(tilt_angles[1])
    rotz = rotmatz(tilt_angles[2])
    if tilt_order =='XYZ':
        rotmat = torch.mm(rotz,torch.mm(roty, rotx))
    elif tilt_order == 'XZY':
        rotmat = torch.mm(roty,torch.mm(rotz, rotx))
    elif tilt_order == 'ZXY':
        rotmat = torch.mm(roty,torch.mm(rotx, rotz))
    elif tilt_order == 'YXZ':
        rotmat = torch.mm(rotz,torch.mm(rotx, roty))
    elif tilt_order == 'ZYX':
         rotmat = torch.mm(rotx,torch.mm(roty, rotz))
    return rotmat

load_voxelized_PLY(ply_filename, voxel_size=[0.05, 0.05, 0.05], device=torch.device('cpu'))

Load a point cloud from a PLY file and convert it into a voxel grid representation.

Parameters:

  • ply_filename (str or Path) – 
           The path to the input PLY file containing triangle data.
  • voxel_size – 
           The size of each voxel in the x, y, and z directions. Default is [0.05, 0.05, 0.05].
  • device – 
           The device on which to perform computations. Default is CPU.

Returns:

  • points ( (Tensor, shape(N, 3)) ) –

    A tensor containing the coordinates of the voxel centers.

  • ground_truth ( (Tensor, shape(Gx * Gy * Gz)) ) –

    A binary tensor where each element indicates whether a corresponding voxel contains at least one point.

Notes
  • The function reads triangle data from the PLY file and computes the center points of these triangles.
  • These points are then processed to create a normalized point cloud, which is converted into a voxel grid.
  • Only voxels containing at least one point are marked as 1 in ground_truth.
  • All operations are performed on the specified device for efficiency.
Source code in odak/learn/tools/transformation.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
def load_voxelized_PLY(
                       ply_filename,
                       voxel_size = [0.05, 0.05, 0.05],
                       device = torch.device('cpu'),
                      ):
    """
    Load a point cloud from a PLY file and convert it into a voxel grid representation.

    Parameters
    ----------
    ply_filename : str or Path
                   The path to the input PLY file containing triangle data.
    voxel_size   : list or tuple, shape (3,), optional
                   The size of each voxel in the x, y, and z directions. Default is [0.05, 0.05, 0.05].
    device       : torch.device, optional
                   The device on which to perform computations. Default is CPU.

    Returns
    -------
    points      : torch.Tensor, shape (N, 3)
                  A tensor containing the coordinates of the voxel centers.
    ground_truth: torch.Tensor, shape (Gx * Gy * Gz,)
                  A binary tensor where each element indicates whether a corresponding voxel contains at least one point.

    Notes
    -----
    - The function reads triangle data from the PLY file and computes the center points of these triangles.
    - These points are then processed to create a normalized point cloud, which is converted into a voxel grid.
    - Only voxels containing at least one point are marked as 1 in `ground_truth`.
    - All operations are performed on the specified device for efficiency.
    """
    triangles = read_PLY(ply_filename)
    points = center_of_triangle(triangles)
    points = torch.as_tensor(points, device = device)
    points = points - points.mean()
    points = points / torch.amax(points)
    ground_truth = torch.ones(points.shape[0], device = device)
    voxel_locations, voxel_grid = point_cloud_to_voxel(points = points, voxel_size = voxel_size,)
    points = voxel_locations.reshape(-1, 3)
    ground_truth = voxel_grid.reshape(-1)
    return points, ground_truth

point_cloud_to_voxel(points, voxel_size=[0.1, 0.1, 0.1])

Convert a point cloud to a voxel grid representation.

Parameters:

  • points – 
         The input point cloud, where each row is a 3D point.
  • voxel_size ((list or Tensor, shape(3)), default: [0.1, 0.1, 0.1] ) – 
         The size of each voxel in the x, y, and z directions. Default is [0.1, 0.1, 0.1].

Returns:

  • locations ( (Tensor, shape(Gx, Gy, Gz, 3)) ) –

    The coordinates of each voxel center in the grid.

  • grid ( (Tensor, shape(Gx, Gy, Gz)) ) –

    A binary voxel grid where 1 indicates the presence of at least one point.

Notes
  • The voxel grid is constructed by discretizing the space between the minimum and maximum coordinates of the point cloud.
  • Only voxels containing at least one point are marked as 1.
  • The output grid is of type float32 and resides on the same device as the input points.
Source code in odak/learn/tools/transformation.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
def point_cloud_to_voxel(
                         points,
                         voxel_size = [0.1, 0.1, 0.1],
                        ):
    """
    Convert a point cloud to a voxel grid representation.

    Parameters
    ----------
    points     : torch.Tensor, shape (N, 3)
                 The input point cloud, where each row is a 3D point.
    voxel_size : list or torch.Tensor, shape (3,), optional
                 The size of each voxel in the x, y, and z directions. Default is [0.1, 0.1, 0.1].

    Returns
    -------
    locations  : torch.Tensor, shape (Gx, Gy, Gz, 3)
                 The coordinates of each voxel center in the grid.
    grid       : torch.Tensor, shape (Gx, Gy, Gz)
                 A binary voxel grid where 1 indicates the presence of at least one point.

    Notes
    -----
    - The voxel grid is constructed by discretizing the space between the minimum and maximum
      coordinates of the point cloud.
    - Only voxels containing at least one point are marked as 1.
    - The output grid is of type float32 and resides on the same device as the input points.
    """
    voxel_size = torch.as_tensor(voxel_size, device = points.device)

    min_coords = points.min(dim = 0).values
    max_coords = points.max(dim = 0).values
    grid_size = ((max_coords - min_coords) / voxel_size).ceil().int()
    points = points - min_coords

    x = torch.linspace(min_coords[0], max_coords[0], grid_size[0], device = points.device)
    y = torch.linspace(min_coords[1], max_coords[1], grid_size[1], device = points.device)
    z = torch.linspace(min_coords[2], max_coords[2], grid_size[2], device = points.device)
    X, Y, Z = torch.meshgrid(x, y, z, indexing='ij')
    locations = torch.stack([X, Y, Z], dim=-1)

    voxel_indices = (points / voxel_size).floor().int()
    mask = (voxel_indices >= 0).all(dim=1) & (voxel_indices < grid_size).all(dim=1)
    voxel_indices = voxel_indices[mask]
    grid = torch.zeros(grid_size.tolist(), dtype=torch.float32, device = points.device)
    grid[voxel_indices[:, 0], voxel_indices[:, 1], voxel_indices[:, 2]] = 1.

    return locations, grid

rotate_points(point, angles=torch.zeros(1, 3), mode='XYZ', origin=torch.zeros(1, 3), offset=torch.zeros(1, 3))

Definition to rotate a given point. Note that rotation is always with respect to 0,0,0.

Parameters:

  • point – 
           A point with size of [3] or [1, 3] or [m, 3].
  • angles – 
           Rotation angles in degrees.
  • mode – 
           Rotation mode determines ordering of the rotations at each axis.
       There are XYZ,YXZ,ZXY and ZYX modes.
  • origin – 
           Reference point for a rotation.
       Expected size is [3] or [1, 3].
  • offset – 
           Shift with the given offset.
       Expected size is [3] or [1, 3] or [m, 3].

Returns:

  • result ( tensor ) –

    Result of the rotation [1 x 3] or [m x 3].

  • rotx ( tensor ) –

    Rotation matrix along X axis [3 x 3].

  • roty ( tensor ) –

    Rotation matrix along Y axis [3 x 3].

  • rotz ( tensor ) –

    Rotation matrix along Z axis [3 x 3].

Source code in odak/learn/tools/transformation.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def rotate_points(
                 point,
                 angles = torch.zeros(1, 3), 
                 mode = 'XYZ', 
                 origin = torch.zeros(1, 3), 
                 offset = torch.zeros(1, 3),
                ):
    """
    Definition to rotate a given point. Note that rotation is always with respect to 0,0,0.

    Parameters
    ----------
    point        : torch.tensor
                   A point with size of [3] or [1, 3] or [m, 3].
    angles       : torch.tensor
                   Rotation angles in degrees. 
    mode         : str
                   Rotation mode determines ordering of the rotations at each axis.
                   There are XYZ,YXZ,ZXY and ZYX modes.
    origin       : torch.tensor
                   Reference point for a rotation.
                   Expected size is [3] or [1, 3].
    offset       : torch.tensor
                   Shift with the given offset.
                   Expected size is [3] or [1, 3] or [m, 3].

    Returns
    ----------
    result       : torch.tensor
                   Result of the rotation [1 x 3] or [m x 3].
    rotx         : torch.tensor
                   Rotation matrix along X axis [3 x 3].
    roty         : torch.tensor
                   Rotation matrix along Y axis [3 x 3].
    rotz         : torch.tensor
                   Rotation matrix along Z axis [3 x 3].
    """
    origin = origin.to(point.device)
    offset = offset.to(point.device)
    angles = angles.to(point.device)

    if len(point.shape) == 1:
        point = point.unsqueeze(0)
    if len(angles.shape) == 1:
        angles = angles.unsqueeze(0)
    if len(origin.shape) == 1:
        origin = origin.unsqueeze(0)
    if len(offset.shape) == 1:
        offset = offset.unsqueeze(0)        

    rotx = rotmatx(angles[:, 0]).unsqueeze(0)
    roty = rotmaty(angles[:, 1]).unsqueeze(0)
    rotz = rotmatz(angles[:, 2]).unsqueeze(0)

    new_points = (point.unsqueeze(1) - origin.unsqueeze(0)).unsqueeze(-1)

    if mode == 'XYZ':
        result = (rotz @ (roty @ (rotx @ new_points)))
    elif mode == 'XZY':
        result = (roty @ (rotz @ (rotx @ new_points)))
    elif mode == 'YXZ':
        result = (rotz @ (rotx @ (roty @ new_points)))
    elif mode == 'ZXY':
        result = (roty @ (rotx @ (rotz @ new_points)))
    elif mode == 'ZYX':
        result = (rotx @ (roty @ (rotz @ new_points)))

    result = result.squeeze(-1)
    result = result + origin.unsqueeze(0) 
    result = result + offset.unsqueeze(0)
    if result.shape[1] == 1:
        result = result.squeeze(1)
    return result, rotx, roty, rotz

rotmatx(angle)

Definition to generate a rotation matrix along X axis.

Parameters:

  • angle – 
           Rotation angles in degrees.

Returns:

  • rotx ( tensor ) –

    Rotation matrix along X axis.

Source code in odak/learn/tools/transformation.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def rotmatx(angle):
    """
    Definition to generate a rotation matrix along X axis.

    Parameters
    ----------
    angle        : torch.tensor
                   Rotation angles in degrees.

    Returns
    ----------
    rotx         : torch.tensor
                   Rotation matrix along X axis.
    """
    angle = torch.deg2rad(angle)
    rotx = torch.zeros(angle.shape[0], 3, 3, device = angle.device)
    rotx[:, 0, 0] = 1.
    rotx[:, 1, 1] = torch.cos(angle)
    rotx[:, 1, 2] = - torch.sin(angle)
    rotx[:, 2, 1] = torch.sin(angle)
    rotx[:, 2, 2] = torch.cos(angle)
    if rotx.shape[0] == 1:
        rotx = rotx.squeeze(0)
    return rotx

rotmaty(angle)

Definition to generate a rotation matrix along Y axis.

Parameters:

  • angle – 
           Rotation angles in degrees.

Returns:

  • roty ( tensor ) –

    Rotation matrix along Y axis.

Source code in odak/learn/tools/transformation.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def rotmaty(angle):
    """
    Definition to generate a rotation matrix along Y axis.

    Parameters
    ----------
    angle        : torch.tensor
                   Rotation angles in degrees.

    Returns
    ----------
    roty         : torch.tensor
                   Rotation matrix along Y axis.
    """
    angle = torch.deg2rad(angle)
    roty = torch.zeros(angle.shape[0], 3, 3, device = angle.device)
    roty[:, 0, 0] = torch.cos(angle)
    roty[:, 0, 2] = torch.sin(angle)
    roty[:, 1, 1] = 1.
    roty[:, 2, 0] = - torch.sin(angle)
    roty[:, 2, 2] = torch.cos(angle)
    if roty.shape[0] == 1:
        roty = roty.squeeze(0)
    return roty

rotmatz(angle)

Definition to generate a rotation matrix along Z axis.

Parameters:

  • angle – 
           Rotation angles in degrees.

Returns:

  • rotz ( tensor ) –

    Rotation matrix along Z axis.

Source code in odak/learn/tools/transformation.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def rotmatz(angle):
    """
    Definition to generate a rotation matrix along Z axis.

    Parameters
    ----------
    angle        : torch.tensor
                   Rotation angles in degrees.

    Returns
    ----------
    rotz         : torch.tensor
                   Rotation matrix along Z axis.
    """
    angle = torch.deg2rad(angle)
    rotz = torch.zeros(angle.shape[0], 3, 3, device = angle.device)
    rotz[:, 0, 0] = torch.cos(angle)
    rotz[:, 0, 1] = - torch.sin(angle)
    rotz[:, 1, 0] = torch.sin(angle)
    rotz[:, 1, 1] = torch.cos(angle)
    rotz[:, 2, 2] = 1.
    if rotz.shape[0] == 1:
        rotz = rotz.squeeze(0)
    return rotz

tilt_towards(location, lookat)

Definition to tilt surface normal of a plane towards a point.

Parameters:

  • location – 
           Center of the plane to be tilted.
  • lookat – 
           Tilt towards this point.

Returns:

  • angles ( list ) –

    Rotation angles in degrees.

Source code in odak/learn/tools/transformation.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
def tilt_towards(location, lookat):
    """
    Definition to tilt surface normal of a plane towards a point.

    Parameters
    ----------
    location     : list
                   Center of the plane to be tilted.
    lookat       : list
                   Tilt towards this point.

    Returns
    ----------
    angles       : list
                   Rotation angles in degrees.
    """
    dx = location[0] - lookat[0]
    dy = location[1] - lookat[1]
    dz = location[2] - lookat[2]
    dist = torch.sqrt(torch.tensor(dx ** 2 + dy ** 2 + dz ** 2))
    phi = torch.atan2(torch.tensor(dy), torch.tensor(dx))
    theta = torch.arccos(dz / dist)
    angles = [0, float(torch.rad2deg(theta)), float(torch.rad2deg(phi))]
    return angles

cross_product(vector1, vector2)

Definition to cross product two vectors and return the resultant vector. Used method described under: http://en.wikipedia.org/wiki/Cross_product

Parameters:

  • vector1 – 
           A vector/ray.
  • vector2 – 
           A vector/ray.

Returns:

  • ray ( tensor ) –

    Array that contains starting points and cosines of a created ray.

Source code in odak/learn/tools/vector.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
def cross_product(vector1, vector2):
    """
    Definition to cross product two vectors and return the resultant vector. Used method described under: http://en.wikipedia.org/wiki/Cross_product

    Parameters
    ----------
    vector1      : torch.tensor
                   A vector/ray.
    vector2      : torch.tensor
                   A vector/ray.

    Returns
    ----------
    ray          : torch.tensor
                   Array that contains starting points and cosines of a created ray.
    """
    angle = torch.cross(vector1[1].T, vector2[1].T)
    angle = torch.tensor(angle)
    ray = torch.tensor([vector1[0], angle], dtype=torch.float32)
    return ray

distance_between_two_points(point1, point2)

Definition to calculate distance between two given points.

Parameters:

  • point1 – 
          First point in X,Y,Z.
  • point2 – 
          Second point in X,Y,Z.

Returns:

  • distance ( Tensor ) –

    Distance in between given two points.

Source code in odak/learn/tools/vector.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def distance_between_two_points(point1, point2):
    """
    Definition to calculate distance between two given points.

    Parameters
    ----------
    point1      : torch.Tensor
                  First point in X,Y,Z.
    point2      : torch.Tensor
                  Second point in X,Y,Z.

    Returns
    ----------
    distance    : torch.Tensor
                  Distance in between given two points.
    """
    point1 = torch.tensor(point1) if not isinstance(point1, torch.Tensor) else point1
    point2 = torch.tensor(point2) if not isinstance(point2, torch.Tensor) else point2

    if len(point1.shape) == 1 and len(point2.shape) == 1:
        distance = torch.sqrt(torch.sum((point1 - point2) ** 2))
    elif len(point1.shape) == 2 or len(point2.shape) == 2:
        distance = torch.sqrt(torch.sum((point1 - point2) ** 2, dim=-1))

    return distance

same_side(p1, p2, a, b)

Definition to figure which side a point is on with respect to a line and a point. See http://www.blackpawn.com/texts/pointinpoly/ for more. If p1 and p2 are on the sameside, this definition returns True.

Parameters:

  • p1 – 
          Point(s) to check.
  • p2 – 
          This is the point check against.
  • a – 
          First point that forms the line.
  • b – 
          Second point that forms the line.
Source code in odak/learn/tools/vector.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def same_side(p1, p2, a, b):
    """
    Definition to figure which side a point is on with respect to a line and a point. See http://www.blackpawn.com/texts/pointinpoly/ for more. If p1 and p2 are on the sameside, this definition returns True.

    Parameters
    ----------
    p1          : list
                  Point(s) to check.
    p2          : list
                  This is the point check against.
    a           : list
                  First point that forms the line.
    b           : list
                  Second point that forms the line.
    """
    ba = torch.subtract(b, a)
    p1a = torch.subtract(p1, a)
    p2a = torch.subtract(p2, a)
    cp1 = torch.cross(ba, p1a)
    cp2 = torch.cross(ba, p2a)
    test = torch.dot(cp1, cp2)
    if len(p1.shape) > 1:
        return test >= 0
    if test >= 0:
        return True
    return False