{"id":9177,"library":"photutils","title":"Photutils","description":"Photutils is an Astropy package for detecting and performing photometry on astronomical sources in image data. It provides tools for source detection, background estimation, aperture and PSF photometry, and image segmentation. Photutils is actively maintained, with new minor versions typically released every 1-3 months, following Astropy's release cycle. The current stable version is 2.3.0.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/astropy/photutils","tags":["astronomy","photometry","image-processing","astropy","source-detection"],"install":[{"cmd":"pip install photutils","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for astronomical data structures, units, WCS, and modeling.","package":"astropy","optional":false},{"reason":"Fundamental for numerical array operations.","package":"numpy","optional":false},{"reason":"Used for various scientific computing tasks, including PSF fitting and filtering.","package":"scipy","optional":false},{"reason":"Optional dependency for visualization and plotting in examples and user scripts.","package":"matplotlib","optional":true}],"imports":[{"symbol":"DAOStarFinder","correct":"from photutils.detection import DAOStarFinder"},{"symbol":"IRAFStarFinder","correct":"from photutils.detection import IRAFStarFinder"},{"symbol":"Background2D","correct":"from photutils.background import Background2D"},{"symbol":"MedianBackground","correct":"from photutils.background import MedianBackground"},{"symbol":"detect_sources","correct":"from photutils.segmentation import detect_sources"},{"symbol":"deblend_sources","correct":"from photutils.segmentation import deblend_sources"},{"symbol":"CircularAperture","correct":"from photutils.aperture import CircularAperture"},{"symbol":"aperture_photometry","correct":"from photutils.aperture import aperture_photometry"},{"note":"SourceProperties and SourceCatalog were removed in v2.0.0; use PropertiesCatalog instead.","wrong":"from photutils.segmentation import SourceProperties","symbol":"PropertiesCatalog","correct":"from photutils.segmentation import PropertiesCatalog"},{"note":"PSF models were removed from photutils.psf in v2.0.0; use astropy.modeling.models instead.","wrong":"from photutils.psf import Gaussian2D","symbol":"Gaussian2D","correct":"from astropy.modeling.models import Gaussian2D"}],"quickstart":{"code":"import numpy as np\nfrom astropy.stats import sigma_clipped_stats\nfrom photutils.detection import DAOStarFinder\nfrom photutils.background import Background2D, MedianBackground\nfrom photutils.aperture import CircularAperture, aperture_photometry\n\n# Create dummy data (replace with your actual FITS data)\ndata = np.random.rand(100, 100) * 100\ny, x = np.mgrid[0:100, 0:100]\ndata += 500 * np.exp(-((x - 20)**2 + (y - 20)**2) / (2 * 5**2)) # Add a star\ndata += 700 * np.exp(-((x - 70)**2 + (y - 80)**2) / (2 * 7**2)) # Add another star\n\n# 1. Estimate background\nmean_bkg, median_bkg, std_bkg = sigma_clipped_stats(data, sigma=3.0)\nbkg = Background2D(data, (50, 50), filter_size=(3, 3),\n                   bkg_estimator=MedianBackground())\ndata_subtracted = data - bkg.background\n\n# 2. Detect sources\nfinder = DAOStarFinder(fwhm=5.0, threshold=3.0 * std_bkg)\nsources = finder(data_subtracted)\n\nif sources is None:\n    print(\"No sources found. Adjust DAOStarFinder parameters.\")\nelse:\n    print(f\"Detected {len(sources)} sources:\")\n    for col in sources.colnames:\n        sources[col].info.format = '%.8g'  # for consistent output\n    print(sources)\n\n    # 3. Perform aperture photometry\n    positions = (sources['xcentroid'], sources['ycentroid'])\n    aperture = CircularAperture(positions, r=8.0)\n    phot_table = aperture_photometry(data_subtracted, aperture)\n\n    print(\"\\nAperture Photometry:\")\n    for col in phot_table.colnames:\n        phot_table[col].info.format = '%.8g'  # for consistent output\n    print(phot_table)","lang":"python","description":"This quickstart demonstrates a basic `photutils` workflow: generating synthetic image data, estimating and subtracting the background, detecting point sources using DAOStarFinder, and performing aperture photometry on the detected sources. This covers fundamental steps in analyzing astronomical images."},"warnings":[{"fix":"Use equivalent models from `astropy.modeling.models` instead (e.g., `from astropy.modeling.models import Gaussian2D`).","message":"PSF models (e.g., `Gaussian2D`, `Moffat2D`) were removed from `photutils.psf` in v2.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use `photutils.segmentation.PropertiesCatalog` instead, which provides similar functionality and is the recommended replacement.","message":"The `SourceProperties` and `SourceCatalog` classes were removed in v2.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For geometrically shaped source apertures, use `CircularAperture`, `RectangularAperture`, `EllipticalAperture`, etc. For pixel-based *background* apertures, use `photutils.aperture.BkgPixelAperture`.","message":"The generic `photutils.aperture.PixelAperture` class was removed in v2.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If your input data is an `astropy.units.Quantity`, extract its numerical value using `.value` (e.g., `data.value`) before passing it to functions that do not explicitly handle `Quantity` inputs for image data. Be mindful of units when interpreting results.","message":"`photutils` functions often expect plain NumPy arrays for image data, even if your data is an `astropy.units.Quantity` object.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check if the returned `sources` table is `None` before attempting to access its columns or perform subsequent operations like photometry (e.g., `if sources is not None:`).","message":"Star-finding algorithms like `DAOStarFinder` and `IRAFStarFinder` return `None` if no sources are found in the image data.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Replace `from photutils.psf import Gaussian2D` with `from astropy.modeling.models import Gaussian2D`.","cause":"Attempting to import PSF models (like Gaussian2D) from `photutils.psf` after the v2.0.0 release.","error":"AttributeError: 'module' object has no attribute 'Gaussian2D'"},{"fix":"Import and use `from photutils.segmentation import PropertiesCatalog` instead, adapting your code to its API.","cause":"Using the `SourceProperties` or `SourceCatalog` classes, which were removed in `photutils` v2.0.0.","error":"NameError: name 'SourceProperties' is not defined"},{"fix":"Extract the numerical value from the `Quantity` using `.value` before passing it to the function (e.g., `data_quantity.value`). Ensure you handle units appropriately in subsequent calculations.","cause":"Passing an `astropy.units.Quantity` object (data with units) directly to a `photutils` function that expects a plain numerical array.","error":"TypeError: 'astropy.units.quantity.Quantity' object cannot be interpreted as an integer"},{"fix":"For geometrically shaped source apertures, use specific classes like `CircularAperture`, `RectangularAperture`, or `EllipticalAperture`. For pixel-based *background* apertures, use `photutils.aperture.BkgPixelAperture`.","cause":"Attempting to import the generic `PixelAperture` class after its removal in `photutils` v2.0.0.","error":"ImportError: cannot import name 'PixelAperture' from 'photutils.aperture'"}]}