class_docstr: The `VolumeLocator` class keeps track of the locations of the
  centers of the volume cells in the local volume coordinates as well as in
  the world coordinates for a voxel grid structure in 3D.
  
      Local coordinates:
          - Represent the locations of the volume cells in the local coordinate
            frame of the volume.
          - The center of the voxel indexed with `[·, ·, 0, 0, 0]` in the volume
            has its 3D local coordinate set to `[-1, -1, -1]`, while the voxel
            at index `[·, ·, depth_i-1, height_i-1, width_i-1]` has its
            3D local coordinate set to `[1, 1, 1]`.
          - The first/second/third coordinate of each of the 3D per-voxel
            XYZ vector denotes the horizontal/vertical/depth-wise position
            respectively. I.e the order of the coordinate dimensions in the
            volume is reversed w.r.t. the order of the 3D coordinate vectors.
          - The intermediate coordinates between `[-1, -1, -1]` and `[1, 1, 1]`.
            are linearly interpolated over the spatial dimensions of the volume.
          - Note that the convention is the same as for the 5D version of the
            `torch.nn.functional.grid_sample` function called with
            the same value of `align_corners` argument.
          - Note that the local coordinate convention of `VolumeLocator`
            (+X = left to right, +Y = top to bottom, +Z = away from the user)
            is *different* from the world coordinate convention of the
            renderer for `Meshes` or `Pointclouds`
            (+X = right to left, +Y = bottom to top, +Z = away from the user).
  
      World coordinates:
          - These define the locations of the centers of the volume cells
            in the world coordinates.
          - They are specified with the following mapping that converts
            points `x_local` in the local coordinates to points `x_world`
            in the world coordinates::
  
                  x_world = (
                      x_local * (volume_size - 1) * 0.5 * voxel_size
                  ) - volume_translation,
  
            here `voxel_size` specifies the size of each voxel of the volume,
            and `volume_translation` is the 3D offset of the central voxel of
            the volume w.r.t. the origin of the world coordinate frame.
            Both `voxel_size` and `volume_translation` are specified in
            the world coordinate units. `volume_size` is the spatial size of
            the volume in form of a 3D vector `[width, height, depth]`.
          - Given the above definition of `x_world`, one can derive the
            inverse mapping from `x_world` to `x_local` as follows::
  
                  x_local = (
                      (x_world + volume_translation) / (0.5 * voxel_size)
                  ) / (volume_size - 1)
  
          - For a trivial volume with `volume_translation==[0, 0, 0]`
            with `voxel_size=-1`, `x_world` would range
            from -(volume_size-1)/2` to `+(volume_size-1)/2`.
  
  Coordinate tensors that denote the locations of each of the volume cells in
  local / world coordinates (with shape `(depth x height x width x 3)`)
  can be retrieved by calling the `VolumeLocator.get_coord_grid()` getter with the
  appropriate `world_coordinates` argument.
  
  Internally, the mapping between `x_local` and `x_world` is represented
  as a `Transform3d` object `VolumeLocator._local_to_world_transform`.
  Users can access the relevant transformations with the
  `VolumeLocator.get_world_to_local_coords_transform()` and
  `VolumeLocator.get_local_to_world_coords_transform()`
  functions.
  
  Example coordinate conversion:
      - For a "trivial" volume with `voxel_size = 1.`,
        `volume_translation=[0., 0., 0.]`, and the spatial size of
        `DxHxW = 5x5x5`, the point `x_world = (-2, 0, 2)` gets mapped
        to `x_local=(-1, 0, 1)`.
      - For a "trivial" volume `v` with `voxel_size = 1.`,
        `volume_translation=[0., 0., 0.]`, the following holds::
  
              torch.nn.functional.grid_sample(
                  v.densities(),
                  v.get_coord_grid(world_coordinates=False),
                  align_corners=align_corners,
              ) == v.densities(),
  
          i.e. sampling the volume at trivial local coordinates
          (no scaling with `voxel_size`` or shift with `volume_translation`)
          results in the same volume.
docstr: Calculate the 3D coordinate grid of the volumetric grid either
  in local (`world_coordinates=False`) or
  world coordinates (`world_coordinates=True`) .
docstr_tok: ["Calculate","the","3D","coordinate","grid","of","the","volumetric","grid","either","in","local","(","`","world_coordinates=False","`",")","or","world","coordinates","(","`","world_coordinates=True","`",")","."]
code: def _calculate_coordinate_grid(
      self, world_coordinates: bool = True
  ) -> torch.Tensor:
      """
      Calculate the 3D coordinate grid of the volumetric grid either
      in local (`world_coordinates=False`) or
      world coordinates (`world_coordinates=True`) .
      """
  
      ba, (de, he, wi) = self._batch_size, self._resolution
      grid_sizes = self.get_grid_sizes()
  
      # generate coordinate axes
      def corner_coord_adjustment(r):
          return 0.0 if self._align_corners else 1.0 / r
  
      vol_axes = [
          torch.linspace(
              -1.0 + corner_coord_adjustment(r),
              1.0 - corner_coord_adjustment(r),
              r,
              dtype=torch.float32,
              device=self.device,
          )
          for r in (de, he, wi)
      ]
  
      # generate per-coord meshgrids
      Z, Y, X = meshgrid_ij(vol_axes)
  
      # stack the coord grids ... this order matches the coordinate convention
      # of torch.nn.grid_sample
      vol_coords_local = torch.stack((X, Y, Z), dim=3)[None].repeat(
          ba, 1, 1, 1, 1
      )
  
      # get grid sizes relative to the maximal volume size
      grid_sizes_relative = (
          torch.tensor(
              [[de, he, wi]],
              device=grid_sizes.device,
              dtype=torch.float32,
          )
          - 1
      ) / (grid_sizes - 1).float()
  
      if (grid_sizes_relative != 1.0).any():
          # if any of the relative sizes != 1.0, adjust the grid
          grid_sizes_relative_reshape = grid_sizes_relative[
              :, [2, 1, 0]
          ][:, None, None, None]
          vol_coords_local *= grid_sizes_relative_reshape
          vol_coords_local += grid_sizes_relative_reshape - 1
  
      if world_coordinates:
          vol_coords = self.local_to_world_coords(vol_coords_local)
      else:
          vol_coords = vol_coords_local
  
      return vol_coords
  
imports: import copy
  from typing import List, Optional, Tuple, Union
  import torch
  from pytorch3d.common.compat import meshgrid_ij
  from pytorch3d.common.datatypes import Device, make_device
  from pytorch3d.transforms import Scale, Transform3d
  from .None import utils
label_desc: Use image node_id 5 for calling the VolumeLocator obj's underlying member method code with example usage: obj._calculate_coordinate_grid(world_coordinates) and returns: vol_coords, unknown