voxcity.importer.transform
==========================

.. py:module:: voxcity.importer.transform

.. autoapi-nested-parse::

   Build the affine that maps OBJ model coordinates to VoxCity voxel indices.

   Convention (rotation=0, axis-aligned domain):
       model +X -> +v (east  / array axis 1)
       model +Y -> +u (north / array axis 0)
       model +Z -> +k (up)
   Positive `rotation` (degrees) rotates the model counter-clockwise in the
   (east, north) plane so that, at rotation=90, model +X points north (+u).

   The composed transform (right-to-left, applied to a column vector
   ``[x, y, z, 1]``)::

       M = Toff @ Sv @ T1 @ R @ S @ T0

     T0  translate model space so ``anchor_model_point`` becomes the origin.
     S   scale model units -> metres (``unit_scale(units)``).
     R   rotate the now-metric (x=east, y=north) vector by ``rotation`` degrees,
         then re-express it in the VoxCity domain's own (u, v) axes -- the domain
         itself may be rotated relative to true north (``domain_rotation``).
     T1  translate to the anchor's position in domain metres (``u_a, v_a``),
         apply the horizontal/vertical ``move`` offset, and shift the vertical
         datum so the DEM minimum sits at z=0 (matching the voxel grid's ground
         datum).
     Sv  scale metres -> voxel indices (divide by ``meshsize``) and add the +1
         vertical offset because the voxelizer seats buildings one voxel above
         the ground voxel (``ground_level = int(dem/voxel_size + 0.5) + 1``).



Functions
---------

.. autoapisummary::

   voxcity.importer.transform.grid_geom_from_voxcity
   voxcity.importer.transform.build_placement_transform


Module Contents
---------------

.. py:function:: grid_geom_from_voxcity(voxcity)

   Recover grid geometry from a VoxCity object via its rectangle_vertices.


.. py:function:: build_placement_transform(voxcity, anchor_lonlat, anchor_elevation, anchor_model_point=(0.0, 0.0, 0.0), rotation=0.0, move=(0.0, 0.0, 0.0), units='m')

   Return a 4x4 affine mapping model coords -> voxel index space (i, j, k).