class_docstr: Samples a fixed number of points along rays which are regularly distributed
  in a batch of rectangular image grids. Points along each ray
  have uniformly-spaced z-coordinates between a predefined
  minimum and maximum depth.
  
  The raysampler first generates a 3D coordinate grid of the following form::
  
         / min_x, min_y, max_depth -------------- / max_x, min_y, max_depth
        /                                        /|
       /                                        / |     ^
      / min_depth                    min_depth /  |     |
      min_x ----------------------------- max_x   |     | image
      min_y                               min_y   |     | height
      |                                       |   |     |
      |                                       |   |     v
      |                                       |   |
      |                                       |   / max_x, max_y,     ^
      |                                       |  /  max_depth        /
      min_x                               max_y /                   / n_pts_per_ray
      max_y ----------------------------- max_x/ min_depth         v
              < --- image_width --- >
  
  In order to generate ray points, `MultinomialRaysampler` takes each 3D point of
  the grid (with coordinates `[x, y, depth]`) and unprojects it
  with `cameras.unproject_points([x, y, depth])`, where `cameras` are an
  additional input to the `forward` function.
  
  Note that this is a generic implementation that can support any image grid
  coordinate convention. For a raysampler which follows the PyTorch3D
  coordinate conventions please refer to `NDCMultinomialRaysampler`.
  As such, `NDCMultinomialRaysampler` is a special case of `MultinomialRaysampler`.
  
  Attributes:
      min_x: The leftmost x-coordinate of each ray's source pixel's center.
      max_x: The rightmost x-coordinate of each ray's source pixel's center.
      min_y: The topmost y-coordinate of each ray's source pixel's center.
      max_y: The bottommost y-coordinate of each ray's source pixel's center.
class_docstr_tok: ["Samples","a","fixed","number","of","points","along","rays","which","are","regularly","distributed","in","a","batch","of","rectangular","image","grids",".","Points","along","each","ray","have","uniformly-spaced","z-coordinates","between","a","predefined","minimum","and","maximum","depth",".","The","raysampler","first","generates","a","3D","coordinate","grid","of","the","following","form",":",":","\/","min_x",",","min_y",",","max_depth","--","--","--","--","--","--","--","\/","max_x",",","min_y",",","max_depth","\/","\/|","\/","\/","|","^","\/","min_depth","min_depth","\/","|","|","min_x","--","--","--","--","--","--","--","--","--","--","--","--","--","--","-","max_x","|","|","image","min_y","min_y","|","|","height","|","|","|","|","|","|","|","v","|","|","|","|","|","\/","max_x",",","max_y",",","^","|","|","\/","max_depth","\/","min_x","max_y","\/","\/","n_pts_per_ray","max_y","--","--","--","--","--","--","--","--","--","--","--","--","--","--","-","max_x\/","min_depth","v","<","--","-","image_width","--","-",">","In","order","to","generate","ray","points",",","`","MultinomialRaysampler","`","takes","each","3D","point","of","the","grid","(","with","coordinates","`","[","x",",","y",",","depth","]","`",")","and","unprojects","it","with","`","cameras.unproject_points","(","[","x",",","y",",","depth","]",")","`",",","where","`","cameras","`","are","an","additional","input","to","the","`","forward","`","function",".","Note","that","this","is","a","generic","implementation","that","can","support","any","image","grid","coordinate","convention",".","For","a","raysampler","which","follows","the","PyTorch3D","coordinate","conventions","please","refer","to","`","NDCMultinomialRaysampler","`",".","As","such",",","`","NDCMultinomialRaysampler","`","is","a","special","case","of","`","MultinomialRaysampler","`",".","Attributes",":","min_x",":","The","leftmost","x-coordinate","of","each","ray","'s","source","pixel","'s","center",".","max_x",":","The","rightmost","x-coordinate","of","each","ray","'s","source","pixel","'s","center",".","min_y",":","The","topmost","y-coordinate","of","each","ray","'s","source","pixel","'s","center",".","max_y",":","The","bottommost","y-coordinate","of","each","ray","'s","source","pixel","'s","center","."]
docstr: Args:
      min_x: The leftmost x-coordinate of each ray's source pixel's center.
      max_x: The rightmost x-coordinate of each ray's source pixel's center.
      min_y: The topmost y-coordinate of each ray's source pixel's center.
      max_y: The bottommost y-coordinate of each ray's source pixel's center.
      image_width: The horizontal size of the image grid.
      image_height: The vertical size of the image grid.
      n_pts_per_ray: The number of points sampled along each ray.
      min_depth: The minimum depth of a ray-point.
      max_depth: The maximum depth of a ray-point.
      n_rays_per_image: If given, this amount of rays are sampled from the grid.
          `n_rays_per_image` and `n_rays_total` cannot both be defined.
      n_rays_total: How many rays in total to sample from the cameras provided. The result
          is as if `n_rays_total_training` cameras were sampled with replacement from the
          cameras provided and for every camera one ray was sampled. If set returns the
          HeterogeneousRayBundle with batch_size=n_rays_total.
          `n_rays_per_image` and `n_rays_total` cannot both be defined.
      unit_directions: whether to normalize direction vectors in ray bundle.
      stratified_sampling: if True, performs stratified random sampling
          along the ray; otherwise takes ray points at deterministic offsets.
docstr_tok: ["Args",":","min_x",":","The","leftmost","x-coordinate","of","each","ray","'s","source","pixel","'s","center",".","max_x",":","The","rightmost","x-coordinate","of","each","ray","'s","source","pixel","'s","center",".","min_y",":","The","topmost","y-coordinate","of","each","ray","'s","source","pixel","'s","center",".","max_y",":","The","bottommost","y-coordinate","of","each","ray","'s","source","pixel","'s","center",".","image_width",":","The","horizontal","size","of","the","image","grid",".","image_height",":","The","vertical","size","of","the","image","grid",".","n_pts_per_ray",":","The","number","of","points","sampled","along","each","ray",".","min_depth",":","The","minimum","depth","of","a","ray-point",".","max_depth",":","The","maximum","depth","of","a","ray-point",".","n_rays_per_image",":","If","given",",","this","amount","of","rays","are","sampled","from","the","grid",".","`","n_rays_per_image","`","and","`","n_rays_total","`","can","not","both","be","defined",".","n_rays_total",":","How","many","rays","in","total","to","sample","from","the","cameras","provided",".","The","result","is","as","if","`","n_rays_total_training","`","cameras","were","sampled","with","replacement","from","the","cameras","provided","and","for","every","camera","one","ray","was","sampled",".","If","set","returns","the","HeterogeneousRayBundle","with","batch_size=n_rays_total",".","`","n_rays_per_image","`","and","`","n_rays_total","`","can","not","both","be","defined",".","unit_directions",":","whether","to","normalize","direction","vectors","in","ray","bundle",".","stratified_sampling",":","if","True",",","performs","stratified","random","sampling","along","the","ray",";","otherwise","takes","ray","points","at","deterministic","offsets","."]
code: def __init__(
      self,
      *,
      min_x: float,
      max_x: float,
      min_y: float,
      max_y: float,
      image_width: int,
      image_height: int,
      n_pts_per_ray: int,
      min_depth: float,
      max_depth: float,
      n_rays_per_image: Optional[int] = None,
      n_rays_total: Optional[int] = None,
      unit_directions: bool = False,
      stratified_sampling: bool = False,
  ) -> None:
      """
      Args:
          min_x: The leftmost x-coordinate of each ray's source pixel's center.
          max_x: The rightmost x-coordinate of each ray's source pixel's center.
          min_y: The topmost y-coordinate of each ray's source pixel's center.
          max_y: The bottommost y-coordinate of each ray's source pixel's center.
          image_width: The horizontal size of the image grid.
          image_height: The vertical size of the image grid.
          n_pts_per_ray: The number of points sampled along each ray.
          min_depth: The minimum depth of a ray-point.
          max_depth: The maximum depth of a ray-point.
          n_rays_per_image: If given, this amount of rays are sampled from the grid.
              `n_rays_per_image` and `n_rays_total` cannot both be defined.
          n_rays_total: How many rays in total to sample from the cameras provided. The result
              is as if `n_rays_total_training` cameras were sampled with replacement from the
              cameras provided and for every camera one ray was sampled. If set returns the
              HeterogeneousRayBundle with batch_size=n_rays_total.
              `n_rays_per_image` and `n_rays_total` cannot both be defined.
          unit_directions: whether to normalize direction vectors in ray bundle.
          stratified_sampling: if True, performs stratified random sampling
              along the ray; otherwise takes ray points at deterministic offsets.
      """
      super().__init__()
      self._n_pts_per_ray = n_pts_per_ray
      self._min_depth = min_depth
      self._max_depth = max_depth
      self._n_rays_per_image = n_rays_per_image
      self._n_rays_total = n_rays_total
      self._unit_directions = unit_directions
      self._stratified_sampling = stratified_sampling
      self.min_x, self.max_x = min_x, max_x
      self.min_y, self.max_y = min_y, max_y
      # get the initial grid of image xy coords
      y, x = meshgrid_ij(
          torch.linspace(
              min_y, max_y, image_height, dtype=torch.float32
          ),
          torch.linspace(
              min_x, max_x, image_width, dtype=torch.float32
          ),
      )
      _xy_grid = torch.stack([x, y], dim=-1)
  
      self.register_buffer("_xy_grid", _xy_grid, persistent=False)
  
imports: import warnings
  from typing import Optional, Tuple, Union
  import torch
  from pytorch3d.common.compat import meshgrid_ij
  from pytorch3d.ops import padded_to_packed
  from pytorch3d.renderer.cameras import CamerasBase
  from pytorch3d.renderer.implicit.utils import HeterogeneousRayBundle, RayBundle
  from torch.nn import functional
label_desc: Use image node_id 1 to create a new MultinomialRaysampler object from inherited base classes: torch.nn with example: obj = MultinomialRaysampler()