pyhiperta.waveform_indexing.waveform_1D_to_2D_maps

pyhiperta.waveform_indexing.waveform_1D_to_2D_maps(pixel_positions: ndarray) → Tuple[ndarray, ndarray][source]

Create the 2D waveform array with “squared geometry” and 1D to 2D indices maps.

To perform fast “neighbour looking” operations such as convolution we need to store the waveform as a 2D array. To fit the hexagonal geometry of the camera into a 2D square grid (the 2D array) we perform a rotation (to align an axis with the 2D array axis) and then deform the other axis to align the hexagonal neighbour on the square grid. If we represent the pixels by their index in the 1D array:

0 1 1 4

2 3 4 -> 0 3 6

5 6 2 5

The algorithm is:

  • find 3 neighbours forming a triangle in the hexagonal representation. The pixels should be such that: the left-most pixel is in between the other two pixels on the y coordinate, eg:

    x

    x

    x

    Such a combination is always possible as the angle in the triangles is 60° and we search a space of 90°. The goal of this is to use the left-most pixel as our 2D grid origin, and the other pixels coordinates will give us the rotation and deformation. In the example, the chosen are pixels are 0, 1 and 3. (1’s y is equal or higher than 0’s y)

  • Rotate all pixels coordinates such that the “down” neighbour is aligned with the 2D grid rows

    x x

    x ->

    x x x

  • Normalize the distances between pixels, so that a pixel is at distance 1 from another on row and column axis (makes next step easier).

  • “Deform” along the row axis to align the pixels on the 2D columns. This is a linear transformation of the x coordinate with respect to the y coordinate:

    ___x x ___ is the deformation to apply for a distance of +1 y

    ->

    x x x x

  • Bin the pixel positions to get their index in the 2D array. This gives the 1D to 2D indices maps.

Notes

This function is slow and runs only on cpu (scipy.cKDTree). It should be used only once to get the mappings for a given camera geometry.

Parameters:

pixel_positions (np.array) – 2D array (shape: (2, N_pixels)) containing the pixels x and y coordinates. This should be the actual pixels positions in the camera. It is important that the referential in which the position are measured has equal metrics on both axis (1m in the real world is 1 on x _and_ y axis)

Returns:

Row and column indices (shape (N_pixels,) each) to use as 1D to 2D indexing maps.

Return type:

Tuple[np.ndarray, np.ndarray]