alproj.project module

alproj.project.modelview_mat(pan_deg, tilt_deg, roll_deg, t_x, t_y, t_z)[source]

Makes an OpenGL-style modelview matrix from euler angles and camera location in world coordinate system. See https://learnopengl.com/Getting-started/Coordinate-Systems .

Derived from alproj.optimize.extrinsic_mat() with coordinate permutation so that the OpenGL renderer and the forward projection use identical rotation logic.

OpenGL vertices are stored as (x_geo, z_geo, y_geo) while extrinsic_mat works in geographic (x, y, z) order. The conversion is:

M_gl = N @ E @ P

where E is the 4x4 extrinsic matrix, P swaps indices 1 and 2 (y <-> z) to convert vertex order to geographic order, and N negates the camera-space Z row so that objects in front of the camera have positive Z – matching the projection matrix convention used by projection_mat() (w_clip = Z).

Parameters:

  • pan_deg (float) – Pan angle in degrees

  • tilt_deg (float) – Tilt angle in degrees

  • roll_deg (float) – Roll angle in degrees

  • t_x (float) – X-axis (latitudinal) coordinate of the camera location in a (planar) geographic coordinate system.

  • t_y (float) – Y-axis (longitudinal) coordinate of the camera location in a (planar) geographic coordinate system.

  • t_z (float) – Z-axis (elevational) coordinate of the camera location in a (planar) geographic coordinate system.

Returns:

modelview_mat – A modelview matrix (flattened, column-major for OpenGL).

Return type:

numpy.ndarray

alproj.project.persp_proj(vert, value, ind, params, offsets=None, min_distance=None)[source]

3D to 2D perspective projection of vertices, with given camera parameters.

Parameters:

  • vert (numpy.ndarray) – Coordinates of vertices, in X(latitudinal), Z(vertical), Y(longitudinal) order.

  • value (numpy.ndarray) – Values of vertices. e.g. colors, geographic coordinates.

  • ind (numpy.ndarray) – Index data of vertices. See http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/ .

  • params (dict) –

    Camera parameters.

    xfloat

    The latitudinal coordinate of the shooting point in planar (e.g. UTM) coordinate reference systems.

    yfloat

    The longitudinal coordinate of the shooting point.

    zfloat

    The vertical coordinate of the shooting point, the unit of z must be the same as x and y (e.g. m).

    fovfloat

    A Field of View in degree.

    panfloat

    A pan angle in degree. North is 0 degree and East is 90 degree. The rotation angles (pan, tilt, roll) follows the OpenCV’s left-handed coordinate system.

    tiltfloat

    A tilt angle in degree. 0 indicates that the camera is horizontal. A positive value indicates that the camera looks up.

    rollfloat

    A roll angle in degree. A positive value indicates that camera leans to the right.

    wint

    An image width in pixel.

    hint

    An image height in pixel

    cxfloat

    The X coordinate of the principle point

    cyfloat

    The Y coordinate of the principle point

    modelstr, default None

    Camera model. If "fisheye", uses equidistant fisheye projection via forward splatting from a wide rectilinear render. If not specified, uses the default pinhole model with distortion.

    a1, a2float

    Distortion coefficients that calibrate non-equal aspect ratio of each pixel. Used by both pinhole and fisheye models.

    k1, k2, k3, k4, k5, k6float

    Radial distortion coefficients. For pinhole: image-space polynomial distortion. For fisheye: angle-space distortion (only k1-k4 used).

    p1, p2float

    Tangential (decentering) distortion coefficients. Used by both pinhole and fisheye models.

    s1, s2, s3, s4float

    Prism distortion coefficients. (pinhole model only)

  • offsets (numpy.ndarray, default None) – Offset for vertex coordinates. Usually returned by alproj.surface.get_colored_surface().

  • min_distance (float, default None) – Minimum distance from camera in coordinate units (e.g., meters). Pixels closer than this distance will be rendered as black. Useful for masking near-field objects that may cause matching errors.

Returns:

raw – Projected result.

Return type:

numpy.ndarray

alproj.project.projection_mat(fov_x_deg, w, h, near=-1, far=1, cx=None, cy=None)[source]

Makes an OpenGL-style projection matrix from Field of View, width, and height of an image. See https://learnopengl.com/Getting-started/Coordinate-Systems .

Parameters:

  • fov_x_deg (float) – Field of View in degrees.

  • w (int) – Width in pixels

  • h (int) – Height in pixels

  • near (float, default -1) – Z-axis coordinate of near plane.

  • far (float, default 1) – Z-axis coordinate of far plane.

  • cx (float, default None) – X-axis coordinate of principal point. If None, w/2.

  • cy (float, default None) – Y-axis coordinate of principal point. If None, h/2.

Returns:

projection_mat – A projection matrix.

Return type:

numpy.ndarray

alproj.project.reverse_proj(array, vert, ind, params, offsets=None, chnames=['B', 'G', 'R'])[source]

2D to 3D reverse-projection (geo-rectification) of given array, onto given surface, with given camera parameters. Reverse-projected array will be returned as pandas.DataFrame with channel names, coordinates in the original array, and coordinates in the geographic coordinate system.

Parameters:

  • array (numpy.ndarray) – Target array, such as landscape photograph. The shape of the array must be (height, width, channels).

  • vert (numpy.ndarray) – Vertex coordinates of the surface.

  • ind (numpy.ndarray) – Index array that shows which three points shape a triangle. See http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/ .

  • params (dict) – Camera parameters. See alproj.project.persp_proj().

  • offsets (numpy.ndarray, default None) – Offset for vertex coordinates. Usually returned by alproj.surface.get_colored_surface().

  • chnames (list of str, default ["B", "G", "R"]) – Channel names of the target array. Default value is [“B”,”G”,”R”] because channel order is BGR in OpenCV.

Returns:

df – Reverse-projected result with column - u , v : The x and y axis coordinates in the original array. - x, y, z : The latitudinal, longitudinal, and vertical coordinates in the reverse-projected coordinate system. - [chnames] : The channel names passed by chnames, such as B, G, R.

Return type:

pandas.DataFrame

alproj.project.sim_image(vert, color, ind, params, offsets=None, min_distance=None)[source]

Renders a simulated image of landscape with given surface and camera parameters.

Parameters:

  • vert (numpy.ndarray) – Vertex coordinates of the surface returned by alproj.surface.get_colored_surface().

  • color (numpy.ndarray) – Vertex colors in RGB, returned by alproj.surface.get_colored_surface().

  • ind (numpy.ndarray) – Index data of vertices, returned by alproj.surface.get_colored_surface().

  • params (dict) – Camera parameters. See alproj.project.persp_proj().

  • offsets (numpy.ndarray, default None) – Offset for vertex coordinates. Usually returned by alproj.surface.get_colored_surface().

  • min_distance (float, default None) – Minimum distance from camera in coordinate units (e.g., meters). Pixels closer than this distance will be rendered as black. Useful for masking near-field objects that may cause matching errors.

Returns:

img – Rendered image in OpenCV’s BGR format.

Return type:

numpy.ndarray

alproj.project.to_geotiff(df, output_path, resolution=1.0, *, crs, bands=['R', 'G', 'B'], interpolate=True, max_dist=1.0, agg_func='mean', nodata=255)[source]

Convert reverse_proj output DataFrame to GeoTIFF.

Parameters:

  • df (pandas.DataFrame) – Output from reverse_proj() containing x, y coordinates and band values.

  • output_path (str) – Output file path for the GeoTIFF.

  • resolution (float, default 1.0) – Pixel resolution in the same unit as the coordinate system.

  • crs (str) – Coordinate Reference System (e.g., “EPSG:6690”). Must match the CRS of the DSM and aerial photograph used for surface generation.

  • bands (list of str, default ["R", "G", "B"]) – Column names in df to use as raster bands.

  • interpolate (bool, default True) – Whether to interpolate missing values using focal statistics.

  • max_dist (float, default 1.0) – Maximum distance (in coordinate units) for interpolation.

  • agg_func (str, default "mean") – Aggregation function for rasterization and interpolation. Options: “mean”, “median”, “max”, “min”.

  • nodata (int, default 255) – NoData value for occluded/missing pixels.

Returns:

Writes GeoTIFF to output_path.

Return type:

None

Examples

>>> georectified = reverse_proj(original, vert, ind, params_optim, offsets)
>>> to_geotiff(georectified, "output.tif", resolution=1.0, crs="EPSG:6690")