Warning, /education/kstars/kstars/fitsviewer/sep/README.md is written in an unsupported language. File is not indexed.
0001 SEP 0002 === 0003 0004 Python and C library for Source Extraction and Photometry 0005 0006 [](https://travis-ci.org/kbarbary/sep) 0007 [](https://ci.appveyor.com/project/kbarbary/sep/branch/master) 0008 [](https://pypi.python.org/pypi/sep) 0009 [](http://dx.doi.org/10.21105/joss.00058) 0010 0011 *"... [it's] an SEP: Somebody Else's Problem." 0012 "Oh, good. I can relax then."* 0013 0014 0015 About 0016 ----- 0017 0018 [Source Extractor](http://www.astromatic.net/software/sextractor) 0019 (Bertin & Arnouts 1996) is a widely used 0020 command-line program for segmentation and analysis of astronomical 0021 images. It reads in FITS format files, performs a configurable series 0022 of tasks, including background estimation, source detection, 0023 deblending and a wide array of source measurements, and finally 0024 outputs a FITS format catalog file. 0025 0026 While Source Extractor is highly useful, the fact that it can only be 0027 used as an executable can limit its applicability or lead to awkward 0028 workflows. There is often a desire to have programmatic access to 0029 perform one or more of the above tasks on in-memory images as part of 0030 a larger custom analysis. 0031 0032 **SEP makes the core algorithms of Source Extractor available as a 0033 library of stand-alone functions and classes.** These operate directly 0034 on in-memory arrays (no FITS files or configuration files). The code 0035 is derived from the Source Extractor code base (written in C) and aims 0036 to produce results compatible with Source Extractor whenever possible. 0037 SEP consists of a C library with no dependencies outside the standard 0038 library, and a Python module that wraps the C library in a Pythonic 0039 API. The Python wrapper operates on NumPy arrays with NumPy as its 0040 only dependency. See below for language-specfic build and usage 0041 instructions. 0042 0043 0044 Python 0045 ------ 0046 0047 **Documentation:** http://sep.readthedocs.io 0048 0049 **Requirements:** 0050 0051 - Tested on Python 2.6, 2.7, 3.3, 3.4, 3.5 0052 - numpy 0053 0054 **Install release version:** 0055 0056 SEP can be installed with [pip](https://pip.pypa.io). After ensuring 0057 that numpy is installed, run 0058 0059 ``` 0060 pip install --no-deps sep 0061 ``` 0062 0063 If you get an error about permissions, you are probably using your 0064 system Python. In this case, I recommend using [pip's "user 0065 install"](https://pip.pypa.io/en/latest/user_guide/#user-installs) 0066 option to install sep into your user directory: 0067 0068 ``` 0069 pip install --no-deps --user sep 0070 ``` 0071 0072 Do **not** install sep or other third-party Python packages using 0073 `sudo` unless you are fully aware of the risks. 0074 0075 0076 **Install development version:** 0077 0078 Building the development version (from github) requires Cython (v0.16 or 0079 higher). Build and install in the usual place: 0080 0081 ``` 0082 ./setup.py install 0083 ``` 0084 0085 **Run tests:** Tests require the [pytest](http://pytest.org) Python 0086 package. To run the tests, execute `./test.py` in the top-level 0087 directory. Some tests require a FITS reader (either fitsio or astropy) 0088 and will be skipped if neither is present. 0089 0090 0091 C Library 0092 --------- 0093 0094 _Note: The build process only works on Linux and OS X._ 0095 0096 **Build:** To build the C library from source: 0097 0098 ``` 0099 make 0100 ``` 0101 0102 **Run tests:** 0103 0104 ``` 0105 make test 0106 ``` 0107 0108 **Install** The static library and header can be installed with 0109 0110 ``` 0111 make install 0112 make PREFIX=/path/to/prefix install 0113 ``` 0114 0115 This will install the shared and static library in `/path/to/prefix/lib` 0116 and header file in `/path/to/prefix/include`. The default prefix is 0117 `/usr/local`. 0118 0119 **API:** The C library API is documented in the header file 0120 [sep.h](src/sep.h). 0121 0122 0123 Contributing 0124 ------------ 0125 0126 Report a bug or documentation issue: http://github.com/kbarbary/sep/issues 0127 0128 Development of SEP takes place on GitHub at 0129 http://github.com/kbarbary/sep. Contributions of bug fixes, 0130 documentation improvements and minor feature additions are welcome via 0131 GitHub pull requests. For major features, it is best to open an issue 0132 discussing the change first. 0133 0134 0135 Citation 0136 -------- 0137 0138 If you use SEP in a publication, please cite the following article in the Journal of Open Source Software: 0139 0140 [](http://dx.doi.org/10.21105/joss.00058) 0141 0142 Please also cite the original Source Extractor paper ([Bertin & Arnouts 0143 1996](http://adsabs.harvard.edu/abs/1996A%26AS..117..393B)). 0144 0145 The DOI for the sep v1.0.0 code release is: 0146 0147 [](http://dx.doi.org/10.5281/zenodo.159035) 0148 0149 License 0150 ------- 0151 0152 The license for all parts of the code derived from Source Extractor is 0153 LGPLv3. The license for code derived from photutils (`src/overlap.h`) 0154 is BSD 3-clause. Finally, the license for the Python wrapper 0155 (`sep.pyx`) is MIT. The license for the library as a whole is 0156 therefore LGPLv3. The license for each file is explicitly stated at 0157 the top of the file and the full text of each license can be found in 0158 `licenses`. 0159 0160 0161 FAQ 0162 --- 0163 0164 **Why isn't the C library part of Source Extractor?** 0165 0166 Source Extractor is *not* designed as a library with an 0167 executable built on top of the library. In Source Extractor, background 0168 estimation, object detection and photometry are deeply integrated into the 0169 Source Extractor executable. Many changes to the code were necessary in 0170 order to put the functionality in stand-alone C functions. It's too much 0171 to ask of the Source Extractor developer to rewrite large parts of the 0172 core of the Source Extractor program with little gain for the executable. 0173 0174 **What sort of changes?** 0175 0176 - Source Extractor reads in only a small portion of each image at a 0177 time. This allows it to keep its memory footprint extremely low and 0178 to operate on images that are much larger than the system's physical 0179 memory. It also means that a FITS reader is deeply integrated into 0180 the code. SEP operates on images in memory, so all the FITS I/O 0181 machinery in Source Extractor is not used here. 0182 0183 - Error handling: When it encounters a problem, Source Extractor 0184 immediately exits with an error message. This is fine for an 0185 executable, but a library function doesn't have that luxury. Instead 0186 it must ensure that allocated memory is freed and return an error 0187 code. 0188 0189 - Options: Source Extractor has many options that affect its behavior. These 0190 are stored in a global structure used throughout the executable. In SEP, 0191 options for a particular function are passed as function parameters. 0192 0193 - Array types: Source Extractor can operate on FITS images containing various 0194 types of data (float, double, int, etc). Internally, it does this by 0195 converting all data to `float` immediately when reading from disk. 0196 SEP does something similar, but in memory: SEP functions typically convert 0197 input arrays to float on the fly within each function, then perform 0198 all operations as floating point. 0199 0200 **Is SEP as fast as Source Extractor?** 0201 0202 It's fast. It should be similar to Source Extractor as a lot of the code 0203 is identical. Source Extractor has the advantage of doing all the 0204 operations (detection and analysis) simultaneously on each image 0205 section, which may confer CPU cache advantages, but this hasn't been 0206 tested at all. On the other hand, depending on your usage SEP might 0207 let you avoid writing files to disk, which is likely to be a bigger 0208 win. 0209 0210 **What happens when Source Extractor is updated in the future?** 0211 0212 SEP can be considered a fork of the Source Extractor code base: it's 0213 development will not track that of Source Extractor in any automated 0214 way. However, the algorithms implemented so far in SEP are stable in 0215 Source Extractor: the SEP code was forked from v2.18.11, yet it is tested 0216 against the results of v2.8.6. This indicates that the algorithms have 0217 not changed in Source Extractor over the last few years. 0218 0219 **In the Python interface, why do I have to byte swap data when using 0220 astropy.io.fits?** 0221 0222 This occurs because FITS files have big-endian [byte 0223 order](http://en.wikipedia.org/wiki/Endianness), whereas most widely 0224 used CPUs have little-endian byte order. In order for the CPU to 0225 operate on the data, it must be byte swapped at *some point.* Some 0226 FITS readers such as [fitsio](http://github.com/esheldon/fitsio) do 0227 the byte swap immediately when reading the data from disk to memory, 0228 returning numpy arrays in native (little-endian) byte order. However, 0229 astropy.io.fits does not (for reasons having to do with memory 0230 mapping). Most of the time you never notice this because when you do 0231 any numpy operations on such arrays, numpy uses an intermediate buffer 0232 to byte swap the array behind the scenes and returns the result as a 0233 native byte order array. Internally, SEP is not using numpy 0234 operations; it's just getting a pointer to the data in the array and 0235 passing it to C code. As the C code does not include functionality to 0236 do buffered byte swapping, the input array must already be in native 0237 byte order. 0238 0239 It would be possible to add buffered byte swapping capability to the 0240 SEP code, but it would increase the code complexity. A simpler 0241 alternative would be to make a byte swapped copy of the entire input 0242 array, whenever necessary. However, this would significantly increase 0243 memory use, and would have to be done repeatedly in multiple SEP 0244 functions: `Background`, `extract`, `sum_circle`, etc. Each would make 0245 a copy of the entire data array. Given these considerations, it seemed 0246 best to just explicitly tell the user to do the byte swap operation 0247 themselves so they could just do it once, immediately after reading in 0248 the data.