class_docstr: A query-only R-tree spatial index created using the
  Sort-Tile-Recursive (STR) [1]_ algorithm.
  
  The tree indexes the bounding boxes of each geometry.  The tree is
  constructed directly at initialization and nodes cannot be added or
  removed after it has been created.
  
  All operations return indices of the input geometries.  These indices
  can be used to index into anything associated with the input geometries,
  including the input geometries themselves, or custom items stored in
  another object of the same length as the geometries.
  
  Bounding boxes limited to two dimensions and are axis-aligned (equivalent to
  the ``bounds`` property of a geometry); any Z values present in geometries
  are ignored for purposes of indexing within the tree.
  
  Any mixture of geometry types may be stored in the tree.
  
  Note: the tree is more efficient for querying when there are fewer
  geometries that have overlapping bounding boxes and where there is greater
  similarity between the outer boundary of a geometry and its bounding box.
  For example, a MultiPolygon composed of widely-spaced individual Polygons
  will have a large overall bounding box compared to the boundaries of its
  individual Polygons, and the bounding box may also potentially overlap many
  other geometries within the tree.  This means that the resulting tree may be
  less efficient to query than a tree constructed from individual Polygons.
  
  Parameters
  ----------
  geoms : sequence
      A sequence of geometry objects.
  node_capacity : int, default 10
      The maximum number of child nodes per parent node in the tree.
  
  References
  ----------
  .. [1] Leutenegger, Scott T.; Edgington, Jeffrey M.; Lopez, Mario A.
     (February 1997). "STR: A Simple and Efficient Algorithm for
     R-Tree Packing".
     https://ia600900.us.archive.org/27/items/nasa_techdoc_19970016975/19970016975.pdf
class_docstr_tok: ["A","query-only","R-tree","spatial","index","created","using","the","Sort-Tile-Recursive","(","STR",")","[","1","]","_","algorithm",".","The","tree","indexes","the","bounding","boxes","of","each","geometry",".","The","tree","is","constructed","directly","at","initialization","and","nodes","can","not","be","added","or","removed","after","it","has","been","created",".","All","operations","return","indices","of","the","input","geometries",".","These","indices","can","be","used","to","index","into","anything","associated","with","the","input","geometries",",","including","the","input","geometries","themselves",",","or","custom","items","stored","in","another","object","of","the","same","length","as","the","geometries",".","Bounding","boxes","limited","to","two","dimensions","and","are","axis-aligned","(","equivalent","to","the","``","bounds","``","property","of","a","geometry",")",";","any","Z","values","present","in","geometries","are","ignored","for","purposes","of","indexing","within","the","tree",".","Any","mixture","of","geometry","types","may","be","stored","in","the","tree",".","Note",":","the","tree","is","more","efficient","for","querying","when","there","are","fewer","geometries","that","have","overlapping","bounding","boxes","and","where","there","is","greater","similarity","between","the","outer","boundary","of","a","geometry","and","its","bounding","box",".","For","example",",","a","MultiPolygon","composed","of","widely-spaced","individual","Polygons","will","have","a","large","overall","bounding","box","compared","to","the","boundaries","of","its","individual","Polygons",",","and","the","bounding","box","may","also","potentially","overlap","many","other","geometries","within","the","tree",".","This","means","that","the","resulting","tree","may","be","less","efficient","to","query","than","a","tree","constructed","from","individual","Polygons",".","Parameters","--","--","--","--","--","geoms",":","sequence","A","sequence","of","geometry","objects",".","node_capacity",":","int",",","default","10","The","maximum","number","of","child","nodes","per","parent","node","in","the","tree",".","References","--","--","--","--","--","..","[","1","]","Leutenegger",",","Scott","T.",";","Edgington",",","Jeffrey","M.",";","Lopez",",","Mario","A",".","(","February","1997",")",".","``","STR",":","A","Simple","and","Efficient","Algorithm","for","R-Tree","Packing","''",".","https",":","\/\/ia600900.us.archive.org\/27\/items\/nasa_techdoc_19970016975\/19970016975.pdf"]
docstr: Return the index of the nearest geometry in the tree for each input
  geometry based on distance within two-dimensional Cartesian space.
  
  This distance will be 0 when input geometries intersect tree geometries.
  
  If there are multiple equidistant or intersected geometries in the tree,
  only a single result is returned for each input geometry, based on the
  order that tree geometries are visited; this order may be
  nondeterministic.
  
  If any input geometry is None or empty, an error is raised.  Any Z
  values present in input geometries are ignored when finding nearest
  tree geometries.
  
  Parameters
  ----------
  geometry : Geometry or array_like
      Input geometries to query the tree.
  
  Returns
  -------
  scalar or ndarray
      Indices of geometries in tree. Return value will have the same shape
      as the input.
  
      None is returned if this index is empty. This may change in
      version 2.0.
  
  See also
  --------
  query_nearest: returns all equidistant geometries, exclusive geometries, and optional distances
  
  Examples
  --------
  >>> from shapely.geometry import Point
  >>> tree = STRtree([Point(i, i) for i in range(10)])
  
  Query the tree for nearest using a scalar geometry:
  
  >>> index = tree.nearest(Point(2.2, 2.2))
  >>> index
  2
  >>> tree.geometries.take(index)
  <POINT (2 2)>
  
  Query the tree for nearest using an array of geometries:
  
  >>> indices = tree.nearest([Point(2.2, 2.2), Point(4.4, 4.4)])
  >>> indices.tolist()
  [2, 4]
  >>> tree.geometries.take(indices).tolist()
  [<POINT (2 2)>, <POINT (4 4)>]
  
  Nearest only return one object if there are multiple equidistant results:
  
  >>> tree = STRtree ([Point(0, 0), Point(0, 0)])
  >>> tree.nearest(Point(0, 0))
  0
docstr_tok: ["Return","the","index","of","the","nearest","geometry","in","the","tree","for","each","input","geometry","based","on","distance","within","two-dimensional","Cartesian","space",".","This","distance","will","be","0","when","input","geometries","intersect","tree","geometries",".","If","there","are","multiple","equidistant","or","intersected","geometries","in","the","tree",",","only","a","single","result","is","returned","for","each","input","geometry",",","based","on","the","order","that","tree","geometries","are","visited",";","this","order","may","be","nondeterministic",".","If","any","input","geometry","is","None","or","empty",",","an","error","is","raised",".","Any","Z","values","present","in","input","geometries","are","ignored","when","finding","nearest","tree","geometries",".","Parameters","--","--","--","--","--","geometry",":","Geometry","or","array_like","Input","geometries","to","query","the","tree",".","Returns","--","--","--","-","scalar","or","ndarray","Indices","of","geometries","in","tree",".","Return","value","will","have","the","same","shape","as","the","input",".","None","is","returned","if","this","index","is","empty",".","This","may","change","in","version","2.0",".","See","also","--","--","--","--","query_nearest",":","returns","all","equidistant","geometries",",","exclusive","geometries",",","and","optional","distances","Examples","--","--","--","--",">",">",">","from","shapely.geometry","import","Point",">",">",">","tree","=","STRtree","(","[","Point","(","i",",","i",")","for","i","in","range","(","10",")","]",")","Query","the","tree","for","nearest","using","a","scalar","geometry",":",">",">",">","index","=","tree.nearest","(","Point","(","2.2",",","2.2",")",")",">",">",">","index","2",">",">",">","tree.geometries.take","(","index",")","<","POINT","(","2","2",")",">","Query","the","tree","for","nearest","using","an","array","of","geometries",":",">",">",">","indices","=","tree.nearest","(","[","Point","(","2.2",",","2.2",")",",","Point","(","4.4",",","4.4",")","]",")",">",">",">","indices.tolist","(",")","[","2",",","4","]",">",">",">","tree.geometries.take","(","indices",")",".tolist","(",")","[","<","POINT","(","2","2",")",">",",","<","POINT","(","4","4",")",">","]","Nearest","only","return","one","object","if","there","are","multiple","equidistant","results",":",">",">",">","tree","=","STRtree","(","[","Point","(","0",",","0",")",",","Point","(","0",",","0",")","]",")",">",">",">","tree.nearest","(","Point","(","0",",","0",")",")","0"]
code: def nearest(self, geometry) -> Union[Any, None]:
      """
          Return the index of the nearest geometry in the tree for each input
          geometry based on distance within two-dimensional Cartesian space.
  
          This distance will be 0 when input geometries intersect tree geometries.
  
          If there are multiple equidistant or intersected geometries in the tree,
          only a single result is returned for each input geometry, based on the
          order that tree geometries are visited; this order may be
          nondeterministic.
  
          If any input geometry is None or empty, an error is raised.  Any Z
          values present in input geometries are ignored when finding nearest
          tree geometries.
  
          Parameters
          ----------
          geometry : Geometry or array_like
              Input geometries to query the tree.
  
          Returns
          -------
          scalar or ndarray
              Indices of geometries in tree. Return value will have the same shape
              as the input.
  
              None is returned if this index is empty. This may change in
              version 2.0.
  
          See also
          --------
          query_nearest: returns all equidistant geometries, exclusive geometries, \
  and optional distances
  
          Examples
          --------
          >>> from shapely.geometry import Point
          >>> tree = STRtree([Point(i, i) for i in range(10)])
  
          Query the tree for nearest using a scalar geometry:
  
          >>> index = tree.nearest(Point(2.2, 2.2))
          >>> index
          2
          >>> tree.geometries.take(index)
          <POINT (2 2)>
  
          Query the tree for nearest using an array of geometries:
  
          >>> indices = tree.nearest([Point(2.2, 2.2), Point(4.4, 4.4)])
          >>> indices.tolist()
          [2, 4]
          >>> tree.geometries.take(indices).tolist()
          [<POINT (2 2)>, <POINT (4 4)>]
  
          Nearest only return one object if there are multiple equidistant results:
  
          >>> tree = STRtree ([Point(0, 0), Point(0, 0)])
          >>> tree.nearest(Point(0, 0))
          0
          """
      if self._tree.count == 0:
          return None
  
      geometry_arr = np.asarray(geometry, dtype=object)
      if is_missing(geometry_arr).any() or is_empty(geometry_arr).any():
          raise ValueError(
              "Cannot determine nearest geometry for empty geometry or "
              "missing value (None)."
          )
      # _tree.nearest returns ndarray with shape (2, 1) -> index in input
      # geometries and index into tree geometries
      indices = self._tree.nearest(np.atleast_1d(geometry_arr))[1]
  
      if geometry_arr.ndim == 0:
          return indices[0]
      else:
          return indices
  
file_path: shapely/shapely/strtree.py
imports: from typing import Any, Iterable, Union
  import numpy
  from shapely import lib
  from shapely._enum import ParamEnum
  from shapely.decorators import UnsupportedGEOSVersionError
  from shapely.geometry.base import BaseGeometry
  from shapely.predicates import is_empty, is_missing
label_desc: Use image node_id 6 for calling the STRtree obj's underlying member method code with example usage: obj.nearest(geometry) and returns: None, indices, indices