wolfhece.wolf_array._header_wolf ================================ .. py:module:: wolfhece.wolf_array._header_wolf .. autoapi-nested-parse:: Header class for WOLF arrays. Contains: - WOLF_ARRAY_* type constants - getkeyblock / decodekeyblock helper functions - header_wolf class (spatial header: origin, resolution, shape, translation, multi-block support) This module is intentionally free of wx, OpenGL, and heavy GUI dependencies so that it can be imported cheaply in non-interactive contexts (CLI tools, unit tests, etc.). Author: HECE - University of Liege, Pierre Archambeau Date: 2024 Copyright (c) 2024 University of Liege. All rights reserved. This script and its content are protected by copyright law. Unauthorized copying or distribution of this file, via any medium, is strictly prohibited. Module Contents --------------- .. py:function:: _(s) .. py:data:: WOLF_ARRAY_HILLSHAPE :value: -1 .. py:data:: WOLF_ARRAY_FULL_SINGLE :value: 1 .. py:data:: WOLF_ARRAY_FULL_DOUBLE :value: 2 .. py:data:: WOLF_ARRAY_SYM_DOUBLE :value: 12 .. py:data:: WOLF_ARRAY_FULL_LOGICAL :value: 4 .. py:data:: WOLF_ARRAY_CSR_DOUBLE :value: 5 .. py:data:: WOLF_ARRAY_FULL_INTEGER :value: 6 .. py:data:: WOLF_ARRAY_FULL_SINGLE_3D :value: 7 .. py:data:: WOLF_ARRAY_FULL_INTEGER8 :value: 8 .. py:data:: WOLF_ARRAY_MB_SINGLE :value: 3 .. py:data:: WOLF_ARRAY_MB_INTEGER :value: 9 .. py:data:: WOLF_ARRAY_FULL_INTEGER16_2 :value: 0 .. py:data:: WOLF_ARRAY_FULL_INTEGER16 :value: 11 .. py:data:: WOLF_ARRAY_MNAP_INTEGER :value: 20 .. py:data:: WOLF_ARRAY_MB .. py:data:: WOLF_ARRAY_FULL_UINTEGER8 :value: 88 .. py:data:: WOLF_ARRAY_FULL_UINTEGER16 :value: 111 .. py:data:: WOLF_ARRAY_FULL_UINTEGER32 :value: 66 .. py:function:: getkeyblock(i, addone=True) -> str Name/Key of a block in the dictionnary of a WolfArrayMB instance For Fortran compatibility, addone is True by default so first block is "block1" and not "block0" .. py:function:: decodekeyblock(key, addone=True) -> int Decode key of a block in the dictionnary of a WolfArrayMB instance For Fortran compatibility, addone is True by default so first block is "block1" and not "block0" .. py:class:: header_wolf Header of WolfArray In case of a mutliblock, the header have informations about all the blocks in head_blocks dictionnary. Block keys are generated by "getkeyblock" function .. py:attribute:: head_blocks :type: dict[str, header_wolf] .. py:attribute:: origx :value: 0.0 .. py:attribute:: origy :value: 0.0 .. py:attribute:: origz :value: 0.0 .. py:attribute:: translx :value: 0.0 .. py:attribute:: transly :value: 0.0 .. py:attribute:: translz :value: 0.0 .. py:attribute:: dx :value: 0.0 .. py:attribute:: dy :value: 0.0 .. py:attribute:: dz :value: 0.0 .. py:attribute:: nbx :value: 0 .. py:attribute:: nby :value: 0 .. py:attribute:: nbz :value: 0 .. py:attribute:: _nullvalue :value: 0.0 .. py:attribute:: _epsg :value: None .. py:property:: epsg .. py:property:: nullvalue .. py:property:: nbdims .. py:property:: shape .. py:property:: nb_blocks .. py:property:: resolution .. py:property:: origin .. py:property:: translation .. py:method:: set_resolution(dx: float, dy: float, dz: float = 0.0) Set resolution .. py:method:: set_origin(x: float, y: float, z: float = 0.0) Set origin :param x: origin along X :param y: origin along Y :param z: origin along Z .. py:method:: get_origin() Return origin .. py:method:: get_resolution() Return resolution .. py:method:: get_translation() Return translation .. py:method:: set_translation(tr_x: float, tr_y: float, tr_z: float = 0.0) Set translation :param tr_x: translation along X :param tr_y: translation along Y :param tr_z: translation along Z .. py:method:: get_bounds(abs=True) Return bounds in coordinates :param abs: if True, add translation to (x, y) (coordinate to global space) :return: tuple of two lists of two floats - ([xmin, xmax],[ymin, ymax]) .. py:method:: get_extent(abs=True) Return extent in coordinates :param abs: if True, add translation to (x, y) (coordinate to global space) :return: list of four floats - [xmin, xmax, ymin, ymax] .. py:method:: get_scale_yoverx() Return the scale of the array (height over width) .. py:method:: get_bounds_ij(abs=False) Return bounds in indices Firstly, get_bounds is called to get bounds in coordinates and then get_ij_from_xy is called to get bounds in indices. :param abs: if True, add translation to (x, y) (coordinate to global space) .. py:method:: get_ij_from_xy(x: float, y: float, z: float = 0.0, scale: float = 1.0, aswolf: bool = False, abs: bool = True, forcedims2: bool = False) -> Union[tuple[numpy.int32, numpy.int32], tuple[numpy.int32, numpy.int32, numpy.int32]] Get indices from coordinates :param x: X coordinate :param y: Y coordinate :param z: Z coordinate (optional) :param scale: scaling of the spatial resolution (dx,dy,[dz]) :param aswolf: if True, return if one-based (as Wolf VB6 or Fortran), otherwise 0-based (default Python standard) :param abs: if True, remove translation from (x, y, [z]) (coordinate from global space) :param forcedims2: if True, force to return only 2 indices even if z is supplied .. py:method:: get_ij_from_xy_array(xy: numpy.ndarray, scale: float = 1.0, aswolf: bool = False, abs: bool = True, forcedims2: bool = False) -> numpy.ndarray Get indices from coordinates :param xy = numpy array containing (x, y, [z]) coordinates - shape (n, 2) or (n, 3) :param scale = scaling of the spatial resolution (dx,dy,[dz]) :param aswolf = if True, return if one-based (as Wolf VB6 or Fortran), otherwise 0-based (default Python standard) :param abs = if True, remove translation from (x, y, [z]) (coordinate from global space) :param forcedims2 = if True, force to return only 2 indices even if z is supplied :return: numpy array containing (i, j, [k]) indices - shape (n, 2) or (n, 3) .. py:method:: get_xy_from_ij(i: int, j: int, k: int = 0, scale: float = 1.0, aswolf: bool = False, abs: bool = True) -> Union[tuple[numpy.float64, numpy.float64], tuple[numpy.float64, numpy.float64, numpy.float64]] Get coordinates from indices :param i = index along X coordinate :param j = index along Y coordinate :param k = index along Z coordinate (optional) :param scale = scaling of the spatial resolution (dx,dy,[dz]) :param aswolf = if True, input is one-based (as Wolf VB6 or Fortran), otherwise 0-based (default Python standard) :param abs = if True, add translation to results (x, y, [z]) (coordinate to global space) .. py:method:: transform() Return the affine transformation. Similar to rasterio.transform.Affine In WOLF, the convention is : - origin is at the lower-left corner - the origin is at the corner of the cell dx, dy, so the center of the cell is at dx/2, dy/2 - X axis is along the rows - i index - Y axis is along the columns - j index So, the affine transformation is : (dx, 0, origx + translx + dx /2, 0, dy, origy + transly + dy/2) .. py:method:: _transform_gmrio() Return the affine transformation. !! Inverted ij/ji convention !! Similar to rasterio.transform.Affine In WOLF, the convention is : - origin is at the lower-left corner - the origin is at the corner of the cell dx, dy, so the center of the cell is at dx/2, dy/2 - X axis is along the rows - i index - Y axis is along the columns - j index So, the affine transformation is : (dx, 0, origx + translx + dx /2, 0, dy, origy + transly + dy/2) .. py:method:: get_xy_from_ij_array(ij: numpy.ndarray, scale: float = 1.0, aswolf: bool = False, abs: bool = True) -> numpy.ndarray Converts array coordinates (numpy cells) to this array's world coodinates. :param ij = numpy array containing (i, j, [k]) indices - shape (n, 2) or (n, 3) :param scale = scaling of the spatial resolution (dx,dy,[dz]) :param aswolf = if True, input is one-based (as Wolf VB6 or Fortran), otherwise 0-based (default Python standard) :param abs = if True, add translation to results (x, y, [z]) (coordinate to global space) ..warning: 'ij' is not the result of np.where() but if you want to use np.where() you can use the following code: ``` np.vstack((ij[0], ij[1])).T ``` .. py:method:: ij2xy(i: int, j: int, k: int = 0, scale: float = 1.0, aswolf: bool = False, abs: bool = True) -> Union[tuple[numpy.float64, numpy.float64], tuple[numpy.float64, numpy.float64, numpy.float64]] alias for get_xy_from_ij .. py:method:: ij2xy_np(ij: numpy.ndarray, scale: float = 1.0, aswolf: bool = False, abs: bool = True) -> numpy.ndarray alias for get_xy_from_ij_array :param ij: numpy array containing (i, j, [k]) indices - like np.argwhere() - shape (n, 2) or (n, 3) :param scale: scaling of the spatial resolution (dx,dy,[dz]) :param aswolf: if True, input is one-based (as Wolf VB6 or Fortran), otherwise 0-based (default Python standard) :param abs: if True, add translation to results (x, y, [z]) (coordinate to global space) ..warning: 'ij' is not the result of np.where() but if you want to use np.where() you can use the following code: ``` np.vstack((ij[0], ij[1])).T ``` :return: numpy array containing (x, y, [z]) coordinates - shape (n, 2) or (n, 3) .. py:method:: ij2xy_np_ij_from_npwhere(ij: numpy.ndarray, scale: float = 1.0, aswolf: bool = False, abs: bool = True) -> numpy.ndarray alias for get_xy_from_ij_array but with ij as np.where result .. py:method:: xy2ij(x: float, y: float, z: float = 0.0, scale: float = 1.0, aswolf: bool = False, abs: bool = True, forcedims2: bool = False) -> Union[tuple[numpy.int32, numpy.int32], tuple[numpy.int32, numpy.int32, numpy.int32]] alias for get_ij_from_xy .. py:method:: xy2ij_np(xy: numpy.ndarray, scale: float = 1.0, aswolf: bool = False, abs: bool = True) -> numpy.ndarray alias for get_ij_from_xy_array :param xy: numpy array containing (x, y, [z]) coordinates - shape (n, 2) or (n, 3) :param scale: scaling of the spatial resolution (dx,dy,[dz]) :param aswolf: if True, return if one-based (as Wolf VB6 or Fortran), otherwise 0-based (default Python standard) :param abs: if True, remove translation from (x, y, [z]) (coordinate from global space) :param forcedims2: if True, force to return only 2 indices even if z is supplied :return : numpy array containing (i, j, [k]) indices - shape (n, 2) or (n, 3) .. py:method:: xyz2ijk_np(xyz: numpy.ndarray, scale: float = 1.0, aswolf: bool = False, abs: bool = True) -> numpy.ndarray alias for get_xy_from_ij_array .. py:method:: ijk2xyz_np(ijk: numpy.ndarray, scale: float = 1.0, aswolf: bool = False, abs: bool = True) -> numpy.ndarray alias for get_xy_from_ij_array .. py:method:: find_intersection(other: header_wolf, ij: bool = False) -> Union[tuple[list[float], list[float]], tuple[list[list[float]], list[list[float]]]] Find the intersection of two header :param other: other header :param ij: if True, return indices instead of coordinates :return: None or tuple of two lists of two floats - ([xmin, xmax],[ymin, ymax]) or indices in each header (if ij=True) [[imin1, imax1], [jmin1, jmax1]], [[imin2, imax2], [jmin2, jmax2]] .. py:method:: find_union(other: Union[header_wolf, list[header_wolf]]) -> tuple[list[float], list[float]] Find the union of two header :return: tuple of two lists of two floats - ([xmin, xmax],[ymin, ymax]) .. py:method:: read_txt_header(filename: str) Read informations from header .txt :param filename: path and filename of the basefile If filename is a Path object, it is converted to a string If filename ends with '.tif', nothing is done because infos are in the .tif file If filename ends with '.flt', a .hdr file must be present and it will be read Otherwise, a filename.txt file must be present .. py:method:: read_header(filename: str) -> header_wolf :classmethod: alias for read_txt_header :param filename: path and filename of the basefile .. py:method:: write_header(filename: str, wolftype: int, forceupdate: bool = False) alias for write_txt_header .. py:method:: write_txt_header(filename: str, wolftype: int, forceupdate: bool = False) Writing the header to a text file Nullvalue is not written :param filename: path and filename with '.txt' extension, which will NOT be automatically added :param wolftype: type of the WOLF_ARRAY_* array :param forceupdate: if True, the file is rewritten even if it already exists .. py:method:: is_like(other: header_wolf, check_mb: bool = False) -> bool Comparison of two headers :param other: other header to compare :param check_mb: if True, the comparison is done on the blocks too The nullvalue is not taken into account .. py:method:: align2grid(x1: float, y1: float, eps: float = 0.0001) -> tuple[float, float] Align coordinates to nearest grid point where the grid is defined by the borders of the array. .. py:method:: _rasterize_segment(x1: float, y1: float, x2: float, y2: float, xstart: float = None, ystart: float = None, n_packet: int = 10) -> list[list[float]] Rasterize a segment according to the grid where the grid is defined by the borders of the array. :param x1: x coordinate of the first point :param y1: y coordinate of the first point :param x2: x coordinate of the second point :param y2: y coordinate of the second point :param xstart: x coordinate of the starting point :param ystart: y coordinate of the starting point :return: numpy array of the rasterized segment .. py:method:: rasterize_vector_along_grid(vector2raster: wolfhece.PyVertexvectors.vector, outformat=None) -> Union[numpy.ndarray, wolfhece.PyVertexvectors.vector] Rasterize a vector according to the grid :param vector2raster: vector to rasterize :param outformat: output format (np.ndarray or vector) .. py:method:: rasterize_zone_along_grid(zone2raster: wolfhece.PyVertexvectors.zone, outformat=None) -> Union[numpy.ndarray, wolfhece.PyVertexvectors.zone] Rasterize a zone according to the grid :param zone2raster: zone to rasterize :param outformat: output format (np.ndarray or zone) .. py:method:: rasterize_vector(vector2raster: wolfhece.PyVertexvectors.vector, outformat=None) -> Union[numpy.ndarray, wolfhece.PyVertexvectors.vector] DEPRECATED since 2.2.8 -- use rasterize_vector_along_grid instead. Will be removed in 2.3.0 .. py:method:: get_xy_infootprint_vect(myvect: vector | Polygon, eps: float = 0.0) -> tuple[numpy.ndarray, numpy.ndarray] Return the coordinates and the indices of the cells in the footprint of a vector. Coordinates are stored in a numpy array of shape (n,2) where n is the number of cells in the footprint. Indices are stored in a numpy array of shape (n,2) where n is the number of cells in the footprint. -> See get_ij_infootprint :param myvect: target vector or Shapely Polygon :param eps: epsilon to avoid rounding errors :return: tuple of two numpy arrays - (coordinates, indices) .. py:method:: get_xy_infootprint(myvect: vector | Polygon, eps: float = 0.0) -> tuple[numpy.ndarray, numpy.ndarray] Return the coordinates and the indices of the cells in the footprint of a vector. Coordinates are stored in a numpy array of shape (n,2) where n is the number of cells in the footprint. Indices are stored in a numpy array of shape (n,2) where n is the number of cells in the footprint. -> See get_ij_infootprint Main principle: - get the indices with 'get_ij_infootprint' - then convert them to coordinates. :param myvect: target vector or Shapely Polygon :param eps: epsilon to avoid rounding errors :return: tuple of two numpy arrays - (coordinates, indices) .. py:method:: get_ij_infootprint_vect(myvect: vector | Polygon, eps: float = 0.0) -> numpy.ndarray Return the indices of the cells in the footprint of a vector. Main principle: - get the bounding box of the vector - convert the bounding box to indices - limit indices to the array size - create a meshgrid of indices Indices are stored in a numpy array of shape (n,2) where n is the number of cells in the footprint. :param myvect: target vector or Shapely Polygon :param eps: epsilon to avoid rounding errors :return: numpy array of indices .. py:method:: get_ij_infootprint(myvect: vector | Polygon, eps: float = 0.0) -> numpy.ndarray Return the indices of the cells in the footprint of a vector Main principle: - get the bounding box of the vector - convert the bounding box to indices - limit indices to the array size - create a meshgrid of indices Indices are stored in a numpy array of shape (n,2) where n is the number of cells in the footprint. :param myvect: target vector or Shapely Polygon :param eps: epsilon to avoid rounding errors :return: numpy array of indices .. py:method:: convert_xy2ij_np(xy) Convert XY coordinates to IJ indices **(0-based)** with Numpy without any check/options :param xy: = numpy array of shape (n,2) with XY coordinates .. py:method:: convert_ij2xy_np(ij) Convert IJ indices **(0-based)** to XY coordinates with Numpy without any check/options :param ij: = numpy array of shape (n,2) with IJ indices .. py:method:: is_in_footprint(x: float, y: float, eps: float = 0.0) -> bool Check if a point is in the footprint of the array :param x: x coordinate :param y: y coordinate :param eps: epsilon to avoid rounding errors :return: True if the point is in the footprint, False otherwise .. py:method:: make(orig: tuple[float, float] = (0.0, 0.0), nb: tuple[int, int] = (0, 0), d: tuple[float, float] = (1.0, 1.0)) :classmethod: .. py:method:: make_from_xybounds_grid(xbounds: tuple[float, float], ybounds: tuple[float, float], d: tuple[float, float] = (1.0, 1.0), grid_to_align: header_wolf = None) :classmethod: Create a header_wolf from the bounds in x and y and the resolution in x and y. If grid_size is provided, the origin will be adjusted to fit the grid size. :param xbounds: tuple of two floats - (xmin, xmax) :param ybounds: tuple of two floats - (ymin, ymax) :param d: tuple of two floats - (dx, dy) :param grid_to_align: header_wolf - grid to adjust the origin :return: header_wolf instance .. py:method:: make_from_header(other: header_wolf) :classmethod: .. py:method:: copy() -> header_wolf Return a copy of the header_wolf instance .. py:method:: from_slices(x_slice: slice, y_slice: slice, d: tuple[float, float] = (1.0, 1.0)) :classmethod: .. py:method:: to_slices() -> tuple[slice, slice] .. py:method:: to_dict(type_to_save: Literal['header_wolf', 'bounds'] = 'header_wolf') -> dict .. py:method:: from_dict(d: dict, dxdy: tuple[float, float] = None, grid: header_wolf = None) -> header_wolf :classmethod: