class aicafe.PointSet (np.ndarray)

This class represents a set of coordinates (points) in a 3D space. The points are supposed to be arranged regularly to form a grid.

It is a subclass of Numpy's ndarray, and thus supports all Numpy functions, methods, and attributes, but also has some additional methods and attributes. To initialize a point set, see __new__() below.

By default, its shape is [..., 3], where [3] indicates the dimension, and [...] indicates the shape of the grid, such as [10] or [3, 5]. For example, a PointSet instance with shape of [2, 4, 3] contains the coordinates of 3D points located on a \(2\times4\) grid.

__new__(cls, array)

To initialize a point set, simply generate an ArrayLike data structure, and then pass it to __new__. No __init__ method is needed because the point set is fully initialized after the __new__ method.

Examples:

You can initialize a point set using numpy array:

>>> array = np.array((1, 2, 3))
>>> ac.PointSet(array)
PointSet([[1, 2, 3]])

or using a list:

>>> array = [[1, 2, 3], [4, 5, 6]]
>>> ac.PointSet(array)
PointSet([[1, 2, 3],
          [4, 5, 6]])

The shape of input must be or can be reshaped to [..., 3]. For example, you can input a 1-D list with length of 6 to get a point set with shape of [2, 3]:

>>> array = [1, 2, 3, 4, 5, 6]
>>> ac.PointSet(array)
PointSet([[1, 2, 3],
          [4, 5, 6]])

Keep the last dimension equal to 3

There is no restriction on changing the last dimension from 3 to any other number. However, all methods and properties of a point set are designed to work only when the last dimension is 3. Therefore, if you want to apply some numpy function or operation to a point set and expect the result is still a valid instance of PointSet, take care to make sure that the result still has shape of [... , 3].

Returns:

Type	Description
PointSet[float]	Initialized point set.

Raises:

Type	Description
ValueError	If array cannot be reshaped to [..., 3].

angle(self, p, unit='radian')

Compute the angle of self and p. Both must be able to be broadcast together.

Parameters:

Name	Type	Description	Default
p	NDArray	Shape [..., 3], array of 3D coordinates.	required
unit	str	The unit of the result, 'radian' or 'degree'.	'radian'

Returns:

Type	Description
np.ndarray	Array with broadcast shape. E.g., when self's shape is [A, 1, 3] and p's shape is [1, B, 3], the result's shape will be [A, B].

Raises:

Type	Description
NotImplementedError	If unit is not 'radian' or 'degree'.

distance(self, p)

Compute the distances from self to p. See aicafe.img.distance for full documentation.

distance2d(self, p)

Compute the distance from self to p in the x-y plane, i.e., the z coordinate will be regarded as 0. See aicafe.img.distance2d for full documentation.

id_float(self)

ndarray[str], shape [...]. The id of self, represented by point coordinates (%.3f).

Examples:

>>> p = ac.PointSet([[1,2,3], [1.1, 2.2, 3.3]])
>>> p.ids_float
['1.000_2.000_3.000' '1.100_2.200_3.300']

id_int(self)

ndarray[str], shape [...]. The id of self, represented by point coordinates (int).

Examples:

>>> p = ac.PointSet([[1,2,3], [1.1, 2.6, 3.3]])
>>> p.ids_int
['1_2_3' '1_2_3']

in_box(self, box, allowance=0)

Determine if self is in a bounding box.

Parameters:

Name	Type	Description	Default
box	'ArrayLike'	[x_min, y_min, z_min, x_max, y_max, z_max] or its reshaped version with shape of [2, 3].	required
allowance	coordinate	Distance allowed for self to leave the box.	0

Returns:

Type	Description
ndarray[bool]	Shape [...]. An element is True if the corresponding point belongs to the closed 3D cube \([x_{\min}-a, x_{\max}+a]\times [y_{\min}-a, y_{\max}+a]\times [z_{\min}-a, z_{\max}+a]\subset\mathbb{R}^3\), where \(a\) is the allowance.

Raises:

Type	Description
ValueError	If box can not be reshaped to [2, 3].

in_img(self, shape)

Determine if self is in an image's coverage.

Parameters:

Name	Type	Description	Default
shape	Sequence[coordinate]	Image shape; must be 3D.	required

Returns:

Type	Description
NDArray	ndarray[bool]: Shape [...]. An element is True if the corresponding point belongs to the closed 3D tube \([0, x-1]\times[0, y-1]\times[0, z-1]\), where \([x, y, z]\) is the image shape, e.g., \([512, 512, 320]\).

Raises:

Type	Description
ValueError	If image shape is not 3D.

mod(self)

The moduli of vectors from the origin \((0, 0, 0)\) to the points in self. See aicafe.img.mod for the function with the same name.

Returns:

Type	Description
NDArray	Shape of [...].

n_points(self)

The number of points in self.

normalize(self)

Normalized self. See aicafe.img.normalize for full documentation.

product(self, p)

Compute the dot product of self and p. Both must be able to be broadcast together.

Parameters:

Name	Type	Description	Default
p	NDArray	Shape [..., 3], array of 3D coordinates.	required

Returns:

Type	Description
NDArray	Array with broadcast shape. E.g., when self's shape is [A, 1, 3] and p's shape is [1, B, 3], the result's shape will be [A, B].

round(self, decimals=0)

Return a point set with each element rounded to the given number of decimals.

Parameters:

Name	Type	Description	Default
decimals	int	Number of decimal places to round to. If it is negative, it specifies the number of positions to the left of the decimal point.	0

Returns:

Type	Description
'PointSet'	Its each point equals to the corresponding point in self after np.round(decimals).