class_docstr: Writer to save GeoTIFF images.
  
  Basic example from Scene:
  
      >>> scn.save_datasets(writer='geotiff')
  
  By default the writer will use the :class:`~satpy.writers.Enhancer` class to
  linear stretch the data (see :doc:`../enhancements`).
  To get Un-enhanced images ``enhance=False`` can be specified which will
  write a geotiff with the data type of the dataset. The fill value defaults
  to the the datasets ``"_FillValue"`` attribute if not ``None`` and no value is
  passed to ``fill_value`` for integer data. In case of float data if ``fill_value``
  is not passed NaN will be used. If a geotiff with a
  certain datatype is desired for example 32 bit floating point geotiffs:
  
      >>> scn.save_datasets(writer='geotiff', dtype=np.float32, enhance=False)
  
  To add custom metadata use `tags`:
  
      >>> scn.save_dataset(dataset_name, writer='geotiff',
      ...                  tags={'offset': 291.8, 'scale': -0.35})
  
  Images are tiled by default. To create striped TIFF files ``tiled=False`` can be specified:
  
      >>> scn.save_datasets(writer='geotiff', tiled=False)
  
  For performance tips on creating geotiffs quickly and making them smaller
  see the :ref:`faq`.
class_docstr_tok: ["Writer","to","save","GeoTIFF","images",".","Basic","example","from","Scene",":",">",">",">","scn.save_datasets","(","writer='geotiff","'",")","By","default","the","writer","will","use","the",":","class",":","`","~satpy.writers.Enhancer","`","class","to","linear","stretch","the","data","(","see",":","doc",":","`","..","\/enhancements","`",")",".","To","get","Un-enhanced","images","``","enhance=False","``","can","be","specified","which","will","write","a","geotiff","with","the","data","type","of","the","dataset",".","The","fill","value","defaults","to","the","the","datasets","``","``","_FillValue","''","``","attribute","if","not","``","None","``","and","no","value","is","passed","to","``","fill_value","``","for","integer","data",".","In","case","of","float","data","if","``","fill_value","``","is","not","passed","NaN","will","be","used",".","If","a","geotiff","with","a","certain","datatype","is","desired","for","example","32","bit","floating","point","geotiffs",":",">",">",">","scn.save_datasets","(","writer='geotiff","'",",","dtype=np.float32",",","enhance=False",")","To","add","custom","metadata","use","`","tags","`",":",">",">",">","scn.save_dataset","(","dataset_name",",","writer='geotiff","'",",","...","tags=","{","'offset","'",":","291.8",",","'scale","'",":","-0.35","}",")","Images","are","tiled","by","default",".","To","create","striped","TIFF","files","``","tiled=False","``","can","be","specified",":",">",">",">","scn.save_datasets","(","writer='geotiff","'",",","tiled=False",")","For","performance","tips","on","creating","geotiffs","quickly","and","making","them","smaller","see","the",":","ref",":","`","faq","`","."]
docstr: Save the image to the given ``filename`` in geotiff_ format.
  
  Note this writer requires the ``rasterio`` library to be installed.
  
  Args:
      img (xarray.DataArray): Data to save to geotiff.
      filename (str): Filename to save the image to. Defaults to
          ``filename`` passed during writer creation. Unlike the
          creation ``filename`` keyword argument, this filename does not
          get formatted with data attributes.
      compute (bool): Compute dask arrays and save the image
          immediately. If ``False`` then the return value can be passed
          to :func:`~satpy.writers.compute_writer_results` to do the
          computation. This is useful when multiple images may share
          input calculations where dask can benefit from not repeating
          them multiple times. Defaults to ``True`` in the writer by
          itself, but is typically passed as ``False`` by callers where
          calculations can be combined.
      dtype (DTypeLike): Numpy data type to save the image as.
          Defaults to 8-bit unsigned integer (``np.uint8``) or the data
          type of the data to be saved if ``enhance=False``. If the
          ``dtype`` argument is provided during writer creation then
          that will be used as the default.
      fill_value (float or int): Value to use where data values are
          NaN/null. If this is specified in the writer configuration
          file that value will be used as the default.
      keep_palette (bool): Save palette/color table to geotiff.
          To be used with images that were palettized with the
          "palettize" enhancement. Setting this to ``True`` will cause
          the colormap of the image to be written as a "color table" in
          the output geotiff and the image data values will represent
          the index values in to that color table. By default, this will
          use the colormap used in the "palettize" operation.
          See the ``cmap`` option for other options. This option defaults
          to ``False`` and palettized images will be converted to RGB/A.
      cmap (trollimage.colormap.Colormap or None): Colormap to save
          as a color table in the output geotiff. See ``keep_palette``
          for more information. Defaults to the palette of the provided
          ``img`` object. The colormap's range should be set to match
          the index range of the palette
          (ex. `cmap.set_range(0, len(colors))`).
      tags (dict): Extra metadata to store in geotiff.
      overviews (list): The reduction factors of the overviews to include
          in the image, eg::
  
              scn.save_datasets(overviews=[2, 4, 8, 16])
  
          If provided as an empty list, then levels will be
          computed as powers of two until the last level has less
          pixels than `overviews_minsize`.
          Default is to not add overviews.
      overviews_minsize (int): Minimum number of pixels for the smallest
          overview size generated when `overviews` is auto-generated.
          Defaults to 256.
      overviews_resampling (str): Resampling method
          to use when generating overviews. This must be the name of an
          enum value from :class:`rasterio.enums.Resampling` and
          only takes effect if the `overviews` keyword argument is
          provided. Common values include `nearest` (default),
          `bilinear`, `average`, and many others. See the rasterio
          documentation for more information.
      scale_offset_tags (Tuple[str, str]): If set, include inclusion of
          scale and offset in the GeoTIFF headers in the GDALMetaData
          tag.  The value of this argument should be a keyword argument
          ``(scale_label, offset_label)``, for example, ``("scale",
          "offset")``, indicating the labels to be used.
      colormap_tag (Optional[str]): If set and the image being saved was
          colorized or palettized then a comma-separated version of the
          colormap is saved to a custom geotiff tag with the provided
          name. See :meth:`trollimage.colormap.Colormap.to_csv` for more
          information.
      driver (Optional[str]): Name of GDAL driver to use to save the
          geotiff. If not specified or None (default) the "GTiff" driver
          is used. Another common option is "COG" for Cloud Optimized
          GeoTIFF. See GDAL documentation for more information.
      tiled (bool): For performance this defaults to ``True``.
          Pass ``False`` to created striped TIFF files.
      include_scale_offset (deprecated, bool): Deprecated.
          Use ``scale_offset_tags=("scale", "offset")`` to include scale
          and offset tags.
  
  .. _geotiff: http://trac.osgeo.org/geotiff/
docstr_tok: ["Save","the","image","to","the","given","``","filename","``","in","geotiff_","format",".","Note","this","writer","requires","the","``","rasterio","``","library","to","be","installed",".","Args",":","img","(","xarray.DataArray",")",":","Data","to","save","to","geotiff",".","filename","(","str",")",":","Filename","to","save","the","image","to",".","Defaults","to","``","filename","``","passed","during","writer","creation",".","Unlike","the","creation","``","filename","``","keyword","argument",",","this","filename","does","not","get","formatted","with","data","attributes",".","compute","(","bool",")",":","Compute","dask","arrays","and","save","the","image","immediately",".","If","``","False","``","then","the","return","value","can","be","passed","to",":","func",":","`","~satpy.writers.compute_writer_results","`","to","do","the","computation",".","This","is","useful","when","multiple","images","may","share","input","calculations","where","dask","can","benefit","from","not","repeating","them","multiple","times",".","Defaults","to","``","True","``","in","the","writer","by","itself",",","but","is","typically","passed","as","``","False","``","by","callers","where","calculations","can","be","combined",".","dtype","(","DTypeLike",")",":","Numpy","data","type","to","save","the","image","as",".","Defaults","to","8-bit","unsigned","integer","(","``","np.uint8","``",")","or","the","data","type","of","the","data","to","be","saved","if","``","enhance=False","``",".","If","the","``","dtype","``","argument","is","provided","during","writer","creation","then","that","will","be","used","as","the","default",".","fill_value","(","float","or","int",")",":","Value","to","use","where","data","values","are","NaN\/null",".","If","this","is","specified","in","the","writer","configuration","file","that","value","will","be","used","as","the","default",".","keep_palette","(","bool",")",":","Save","palette\/color","table","to","geotiff",".","To","be","used","with","images","that","were","palettized","with","the","``","palettize","''","enhancement",".","Setting","this","to","``","True","``","will","cause","the","colormap","of","the","image","to","be","written","as","a","``","color","table","''","in","the","output","geotiff","and","the","image","data","values","will","represent","the","index","values","in","to","that","color","table",".","By","default",",","this","will","use","the","colormap","used","in","the","``","palettize","''","operation",".","See","the","``","cmap","``","option","for","other","options",".","This","option","defaults","to","``","False","``","and","palettized","images","will","be","converted","to","RGB\/A",".","cmap","(","trollimage.colormap.Colormap","or","None",")",":","Colormap","to","save","as","a","color","table","in","the","output","geotiff",".","See","``","keep_palette","``","for","more","information",".","Defaults","to","the","palette","of","the","provided","``","img","``","object",".","The","colormap","'s","range","should","be","set","to","match","the","index","range","of","the","palette","(","ex",".","`","cmap.set_range","(","0",",","len","(","colors",")",")","`",")",".","tags","(","dict",")",":","Extra","metadata","to","store","in","geotiff",".","overviews","(","list",")",":","The","reduction","factors","of","the","overviews","to","include","in","the","image",",","eg",":",":","scn.save_datasets","(","overviews=","[","2",",","4",",","8",",","16","]",")","If","provided","as","an","empty","list",",","then","levels","will","be","computed","as","powers","of","two","until","the","last","level","has","less","pixels","than","`","overviews_minsize","`",".","Default","is","to","not","add","overviews",".","overviews_minsize","(","int",")",":","Minimum","number","of","pixels","for","the","smallest","overview","size","generated","when","`","overviews","`","is","auto-generated",".","Defaults","to","256.","overviews_resampling","(","str",")",":","Resampling","method","to","use","when","generating","overviews",".","This","must","be","the","name","of","an","enum","value","from",":","class",":","`","rasterio.enums.Resampling","`","and","only","takes","effect","if","the","`","overviews","`","keyword","argument","is","provided",".","Common","values","include","`","nearest","`","(","default",")",",","`","bilinear","`",",","`","average","`",",","and","many","others",".","See","the","rasterio","documentation","for","more","information",".","scale_offset_tags","(","Tuple","[","str",",","str","]",")",":","If","set",",","include","inclusion","of","scale","and","offset","in","the","GeoTIFF","headers","in","the","GDALMetaData","tag",".","The","value","of","this","argument","should","be","a","keyword","argument","``","(","scale_label",",","offset_label",")","``",",","for","example",",","``","(","``","scale","''",",","``","offset","''",")","``",",","indicating","the","labels","to","be","used",".","colormap_tag","(","Optional","[","str","]",")",":","If","set","and","the","image","being","saved","was","colorized","or","palettized","then","a","comma-separated","version","of","the","colormap","is","saved","to","a","custom","geotiff","tag","with","the","provided","name",".","See",":","meth",":","`","trollimage.colormap.Colormap.to_csv","`","for","more","information",".","driver","(","Optional","[","str","]",")",":","Name","of","GDAL","driver","to","use","to","save","the","geotiff",".","If","not","specified","or","None","(","default",")","the","``","GTiff","''","driver","is","used",".","Another","common","option","is","``","COG","''","for","Cloud","Optimized","GeoTIFF",".","See","GDAL","documentation","for","more","information",".","tiled","(","bool",")",":","For","performance","this","defaults","to","``","True","``",".","Pass","``","False","``","to","created","striped","TIFF","files",".","include_scale_offset","(","deprecated",",","bool",")",":","Deprecated",".","Use","``","scale_offset_tags=","(","``","scale","''",",","``","offset","''",")","``","to","include","scale","and","offset","tags",".","..","_geotiff",":","http",":","\/\/trac.osgeo.org\/geotiff\/"]
code: def save_image(  # noqa: D417
      self,
      img: XRImage,
      filename: Optional[str] = None,
      compute: bool = True,
      dtype: Optional[DTypeLike] = None,
      fill_value: Optional[Union[int, float]] = None,
      keep_palette: bool = False,
      cmap: Optional[Colormap] = None,
      tags: Optional[dict[str, Any]] = None,
      overviews: Optional[list[int]] = None,
      overviews_minsize: int = 256,
      overviews_resampling: Optional[str] = None,
      include_scale_offset: bool = False,
      scale_offset_tags: Optional[tuple[str, str]] = None,
      colormap_tag: Optional[str] = None,
      driver: Optional[str] = None,
      tiled: bool = True,
      **kwargs,
  ):
      """Save the image to the given ``filename`` in geotiff_ format.
  
      Note this writer requires the ``rasterio`` library to be installed.
  
      Args:
          img (xarray.DataArray): Data to save to geotiff.
          filename (str): Filename to save the image to. Defaults to
              ``filename`` passed during writer creation. Unlike the
              creation ``filename`` keyword argument, this filename does not
              get formatted with data attributes.
          compute (bool): Compute dask arrays and save the image
              immediately. If ``False`` then the return value can be passed
              to :func:`~satpy.writers.compute_writer_results` to do the
              computation. This is useful when multiple images may share
              input calculations where dask can benefit from not repeating
              them multiple times. Defaults to ``True`` in the writer by
              itself, but is typically passed as ``False`` by callers where
              calculations can be combined.
          dtype (DTypeLike): Numpy data type to save the image as.
              Defaults to 8-bit unsigned integer (``np.uint8``) or the data
              type of the data to be saved if ``enhance=False``. If the
              ``dtype`` argument is provided during writer creation then
              that will be used as the default.
          fill_value (float or int): Value to use where data values are
              NaN/null. If this is specified in the writer configuration
              file that value will be used as the default.
          keep_palette (bool): Save palette/color table to geotiff.
              To be used with images that were palettized with the
              "palettize" enhancement. Setting this to ``True`` will cause
              the colormap of the image to be written as a "color table" in
              the output geotiff and the image data values will represent
              the index values in to that color table. By default, this will
              use the colormap used in the "palettize" operation.
              See the ``cmap`` option for other options. This option defaults
              to ``False`` and palettized images will be converted to RGB/A.
          cmap (trollimage.colormap.Colormap or None): Colormap to save
              as a color table in the output geotiff. See ``keep_palette``
              for more information. Defaults to the palette of the provided
              ``img`` object. The colormap's range should be set to match
              the index range of the palette
              (ex. `cmap.set_range(0, len(colors))`).
          tags (dict): Extra metadata to store in geotiff.
          overviews (list): The reduction factors of the overviews to include
              in the image, eg::
  
                  scn.save_datasets(overviews=[2, 4, 8, 16])
  
              If provided as an empty list, then levels will be
              computed as powers of two until the last level has less
              pixels than `overviews_minsize`.
              Default is to not add overviews.
          overviews_minsize (int): Minimum number of pixels for the smallest
              overview size generated when `overviews` is auto-generated.
              Defaults to 256.
          overviews_resampling (str): Resampling method
              to use when generating overviews. This must be the name of an
              enum value from :class:`rasterio.enums.Resampling` and
              only takes effect if the `overviews` keyword argument is
              provided. Common values include `nearest` (default),
              `bilinear`, `average`, and many others. See the rasterio
              documentation for more information.
          scale_offset_tags (Tuple[str, str]): If set, include inclusion of
              scale and offset in the GeoTIFF headers in the GDALMetaData
              tag.  The value of this argument should be a keyword argument
              ``(scale_label, offset_label)``, for example, ``("scale",
              "offset")``, indicating the labels to be used.
          colormap_tag (Optional[str]): If set and the image being saved was
              colorized or palettized then a comma-separated version of the
              colormap is saved to a custom geotiff tag with the provided
              name. See :meth:`trollimage.colormap.Colormap.to_csv` for more
              information.
          driver (Optional[str]): Name of GDAL driver to use to save the
              geotiff. If not specified or None (default) the "GTiff" driver
              is used. Another common option is "COG" for Cloud Optimized
              GeoTIFF. See GDAL documentation for more information.
          tiled (bool): For performance this defaults to ``True``.
              Pass ``False`` to created striped TIFF files.
          include_scale_offset (deprecated, bool): Deprecated.
              Use ``scale_offset_tags=("scale", "offset")`` to include scale
              and offset tags.
  
      .. _geotiff: http://trac.osgeo.org/geotiff/
  
      """
      filename = filename or self.get_filename(**img.data.attrs)
  
      gdal_options = self._get_gdal_options(kwargs)
      if fill_value is None:
          # fall back to fill_value from configuration file
          fill_value = self.info.get("fill_value")
  
      dtype = dtype if dtype is not None else self.dtype
      if dtype is None and self.enhancer is not False:
          dtype = np.uint8
      elif dtype is None:
          dtype = img.data.dtype.type
  
      if "alpha" in kwargs:
          raise ValueError(
              "Keyword 'alpha' is automatically set based on 'fill_value' "
              "and should not be specified"
          )
      if np.issubdtype(dtype, np.floating):
          if img.mode != "L":
              raise ValueError(
                  "Image must be in 'L' mode for floating "
                  "point geotiff saving"
              )
          if fill_value is None:
              LOG.debug(
                  "Alpha band not supported for float geotiffs, "
                  "setting fill value to 'NaN'"
              )
              fill_value = np.nan
      if keep_palette and cmap is None and img.palette is not None:
          from satpy.enhancements import create_colormap
  
          cmap = create_colormap({"colors": img.palette})
          cmap.set_range(0, len(img.palette) - 1)
  
      if tags is None:
          tags = {}
      tags.update(self.tags)
  
      return img.save(
          filename,
          fformat="tif",
          driver=driver,
          fill_value=fill_value,
          dtype=dtype,
          compute=compute,
          keep_palette=keep_palette,
          cmap=cmap,
          tags=tags,
          include_scale_offset_tags=include_scale_offset,
          scale_offset_tags=scale_offset_tags,
          colormap_tag=colormap_tag,
          overviews=overviews,
          overviews_resampling=overviews_resampling,
          overviews_minsize=overviews_minsize,
          tiled=tiled,
          **gdal_options,
      )
  
file_path: satpy/satpy/writers/geotiff.py
imports: from __future__ import annotations
  import logging
  from typing import Any, Optional, Union
  import numpy
  import rasterio
  from trollimage.colormap import Colormap
  from trollimage.xrimage import XRImage
  from satpy._compat import DTypeLike
  from satpy.writers import ImageWriter
label_desc: Use image node_id 3 for calling the GeoTIFFWriter obj's underlying member method code with example usage: obj.save_image(img, filename, compute, dtype, fill_value, keep_palette, cmap, tags, overviews, overviews_minsize, overviews_resampling, include_scale_offset, scale_offset_tags, colormap_tag, driver, tiled) and returns: img