SpecProc 1.0.0__tar.gz → 1.0.2__tar.gz

{specproc-1.0.0 → specproc-1.0.2}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: SpecProc
-Version: 1.0.0
+Version: 1.0.2
 Summary: A spectral processing tool
 Author-email: "Niu, Hubiao" <niuhubiao@xao.ac.cn>
-License: MIT
-Project-URL: Homepage, https://github.com/yourusername/specproc
-Project-URL: Repository, https://github.com/yourusername/specproc
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/abiao-github/SpecProc
+Project-URL: Repository, https://github.com/abiao-github/SpecProc
+Project-URL: Releases, https://github.com/abiao-github/SpecProc/releases
 Keywords: spectroscopy,FITS,data-reduction
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
@@ -17,12 +18,13 @@ Requires-Dist: scipy
 Requires-Dist: astropy
 Requires-Dist: matplotlib
 Requires-Dist: PyQt5
-Requires-Dist: configparser
 Dynamic: license-file
 
 # SpecProc: PyQt GUI for Spectrograph Data Reduction
 
-![SpecProc GUI](docs/SpecProc.png)
+**English** | [简体中文](README_CN.md)
+
+![SpecProc GUI](docs/SpecProcGUI.png)
 
 A complete PyQt-based graphical interface for reducing slit/chelle spectrograph FITS data.
 
@@ -48,9 +50,9 @@ A complete PyQt-based graphical interface for reducing slit/chelle spectrograph
 2. **Apertures Tracing** - Master flat generation and echelle aperture tracing
 3. **Scattered Light Subtraction** - Inter-aperture background modeling and removal (astropy convolution or spline)
 4. **2D Flat-Field Correction** - 2D pixel flat correction
-5. **1D Spectrum Extraction** - 1D spectrum extraction for each aperture (sum or optimal)
+5. **1D Spectrum Extraction** - optimal extraction for each aperture
 6. **De-blazing** - Blaze function correction
-7. **Wavelength Calibration** - Wavelength calibration applied to both sum and optimal de-blazed 1D spectra
+7. **Wavelength Calibration** - Wavelength calibration applied to the optimal de-blazed 1D spectra
 8. **Order Stitching** - Merge overlapping neighboring orders into a continuous 1D spectrum
 
 ### Interactive GUI
@@ -91,7 +93,7 @@ specproc
 
 ### Method 2: Using conda
 
-Conda provides a complete environment with all dependencies. Two installation options:
+conda is a good fit when you want an isolated environment. SpecProc is **not published on conda-forge**, so the recipe is: create the conda environment, then `pip install` the package into it.
 
 #### Option 2.1: Install in existing conda environment
 
@@ -99,8 +101,8 @@ Conda provides a complete environment with all dependencies. Two installation op
 # Activate your conda environment
 conda activate your_environment
 
-# Install SpecProc from conda-forge
-conda install -c conda-forge specproc
+# Install SpecProc with pip
+pip install specproc
 
 # Launch application
 specproc
@@ -110,11 +112,12 @@ specproc
 
 ```bash
 # Create new conda environment for SpecProc
-conda create -n specproc python=3.8
+conda create -n specproc python=3.11
 conda activate specproc
 
-# Install SpecProc and all dependencies
-conda install -c conda-forge specproc
+# Scientific/GUI dependencies from conda, SpecProc itself from pip
+conda install -c conda-forge numpy scipy astropy matplotlib pyqt -y
+pip install specproc
 
 # Launch application
 specproc
@@ -122,7 +125,7 @@ specproc
 
 **Notes:**
 - Recommended for users who want an isolated environment
-- All dependencies are managed by conda
+- Core dependencies are managed by conda; SpecProc itself is installed with pip
 - Python 3.7-3.11 are supported
 
 ### Method 3: Installing from Source
@@ -193,8 +196,8 @@ specproc --config ./specproc.cfg
 │   │   ├── overscan_corrected/ # Overscan-corrected images and diagnostic plots
 │   │   ├── bias_subtracted/    # Master bias and bias-corrected images
 │   │   └── cosmic_corrected/   # Cosmic ray corrected science images (if enabled)
-│   ├── step2_flat/             # Step 2: Master flat field, blaze profiles, and diagnostic plots
-│   ├── step3_background/       # Step 3: Background model and diagnostic plots
+│   ├── step2_trace/            # Step 2: Master flat field, blaze profiles, and diagnostic plots
+│   ├── step3_scatterlight/     # Step 3: Background model and diagnostic plots
 │   ├── step5_extraction/       # Step 5: Extracted 1D spectra and diagnostic plots
 │   ├── step6_deblazing/        # Step 6: De-blazed spectra and diagnostic plots (if saved)
 │   └── step7_wavelength/       # Step 7: Final wavelength calibrated 1D spectra and plots
@@ -206,7 +209,7 @@ specproc --config ./specproc.cfg
 **Note**:
 - ❌ Do NOT run `specproc` in SpecProc source directory (`/path/to/SpecProc`)
 - ✅ Run `specproc` in your working directory
-- ✅ `rawdata` and `output` will be created in your working directory
+- ✅ `output` will be created in your working directory
 
 ## Configuration
 
@@ -272,12 +275,13 @@ rawdata_path = ./20241102_hrs
 #   │   ├── overscan_corrected/ # Overscan-corrected images
 #   │   ├── bias_subtracted/    # Master bias and bias-corrected images
 #   │   └── cosmic_corrected/   # Cosmic ray corrected science images (if enabled)
-#   ├── step2_flat/             # Step 2: Master flat field with blaze profiles
-#   ├── step3_background/       # Step 3: Background model
+#   ├── step2_trace/            # Step 2: Master flat field with blaze profiles
+#   ├── step3_scatterlight/     # Step 3: Background model
 #   ├── step5_extraction/       # Step 5: Extracted 1D spectra (pixel space)
 #   ├── step6_deblazing/        # Step 6: De-blazed spectra (if saved)
 #   └── step7_wavelength/       # Step 7: Final wavelength calibrated 1D spectra
 output_path = output
+```
 
 #### Path Examples
 
@@ -317,8 +321,8 @@ Control which processing steps to save intermediate results:
 # Default is 'yes' for all steps
 save_overscan = yes        # Step 1: Overscan correction (saves to output/step1_basic/overscan_corrected/)
 save_bias = yes             # Step 1: Bias correction (saves to output/step1_basic/bias_subtracted/)
-save_flat = yes              # Step 2: Flat fielding (saves master flat to output/step2_flat/)
-save_background = yes        # Step 3: Background subtraction (saves model to output/step3_background/)
+save_flat = yes              # Step 2: Flat fielding (saves master flat to output/step2_trace/)
+save_background = yes        # Step 3: Background subtraction (saves model to output/step3_scatterlight/)
 save_cosmic = yes           # Step 1: Cosmic ray correction (saves to output/step1_basic/cosmic_corrected/)
 save_extraction = yes       # Step 5: Spectrum extraction (saves to output/step5_extraction/)
 save_deblaze = yes          # Step 6: De-blazing (saves to output/step6_deblazing/)
@@ -327,7 +331,7 @@ save_wlcalib = yes          # Step 7: Wavelength calibration (saves solution to
 
 **Effect**:
 - If a step is set to `no`, the corresponding output subdirectory will NOT be created
-- Final spectra are always saved to `output/step8_final_spectra/` regardless of these settings
+- Final spectra are always saved to `output/step8_stitching/` regardless of these settings
 - Diagnostic plots can be saved in corresponding step subdirectories
 - In GUI, there should be corresponding checkboxes to enable/disable saving
 - Default: All steps save intermediate results
@@ -353,13 +357,11 @@ linelist_path = calib_data/linelists/
 # For Xinglong 2.16m HRS: thar-noao.dat is recommended
 linelist_file = thar-noao.dat
 
-# Use pre-identified calibration files (optional)
-use_precomputed_calibration = yes
-calibration_path = calib_data/telescopes/xinglong216hrs/
+# Use pre-identified anchor lines (optional)
+anchor_file = calib_data/telescopes/xinglong216hrs/xinglong216_thar_anchors.csv
 
-# Specific calibration file to use (optional)
-# Use latest: wlcalib_20211123011_A.fits
-calibration_file = wlcalib_20211123011_A.fits
+# Full lamp catalogue used for the final wavelength fit
+full_linelist = calib_data/linelists/thar-noao.dat
 ```
 
 ## Processing Pipeline
@@ -437,16 +439,20 @@ calibration_file = wlcalib_20211123011_A.fits
 - **Output**: Wavelength-calibrated 1D spectra
 - **Note**: Establishes the physical wavelength scale for each order.
 
+#### STEP 8: Order Stitching
+- **Input**: Wavelength-calibrated spectra of all orders
+- **Processing**:
+  - Overlap neighbouring orders in the common wavelength range
+  - Combine them with an SNR-weighted average
+- **Output**: One continuous, stitched 1D spectrum
+- **Note**: Produces the final science-ready 1D spectrum for absorption-line analysis.
 
 ## Usage
 
-### GUI Mode (Default)
+### GUI Mode
 
 ```bash
-# Launch GUI (default mode)
-specproc
-
-# Or explicitly specify GUI mode
+# Launch GUI (must be requested explicitly; the default is CLI)
 specproc --mode gui
 
 # With custom config file
@@ -465,8 +471,8 @@ specproc --config /path/to/config.cfg
 ### CLI Mode (Command Line)
 
 ```bash
-# Run CLI mode
-specproc --mode cli
+# CLI is the default: process FITS files in the current directory
+specproc
 
 # Or with custom config file
 specproc --mode cli --config /path/to/config.cfg
@@ -474,8 +480,8 @@ specproc --mode cli --config /path/to/config.cfg
 # Or select a packaged telescope profile by name, and process data with it
 specproc --mode cli --config XL216_hrs 20241102_hrs
 
-# Without input data, the named profile is copied to ./specproc.cfg instead
-# of being used directly, so it can be reviewed/customized first
+# Without input data, the profile config is copied with its packaged filename
+# so it can be reviewed/customized first
 specproc --config MSTG193_slit
 ```
 
@@ -486,23 +492,84 @@ per supported telescope/instrument under `src/specproc/config/` (e.g.
 to that packaged file automatically — no need to type the full path. Run
 `specproc --help` to see the list of available profiles.
 
+When no `--config` is given, CLI processing reads `TELESCOP`/`INSTRUME` from the
+input FITS headers, selects the matching packaged profile, copies it to
+`./specproc.cfg` if that file does not already exist, and uses that working copy.
+The combined profile names currently reserved are `mstg193slit`,
+`xinglong216hrs`, `xinglong216bfosc` and `lijiang24hrs`. The profile can also
+be forced explicitly:
+
+```bash
+specproc --profile mstg193slit raw_dir
+```
+
+If no telescope/instrument metadata is available, create an editable working
+config with `specproc --config` and adjust it for the observation.
+For MSTG data the slit pipeline also selects `mstg193slit_anchors_R.csv` or
+`mstg193slit_anchors_B.csv` from `INSTRUME` when the corresponding file exists.
+
+**Nanshan 1.2m fibre echelle** (`--profile nanshan12`, auto-detected from
+`SWOWNER = 'nanshan'`; config `NS12_hrs`): the spectrograph has high, mid and low
+resolution modes that the FITS headers do not distinguish, so with
+`[data] auto_resolution = yes` the input frames are split automatically and each
+group is reduced separately into `output/<high|mid|low>/`:
+
+- flat / target / standard frames: by the order spacing of the bright bands
+  (autocorrelation of the cross-dispersion profile: about 10-12 px high, 16-17 px mid,
+  85-100 px low);
+- ThAr lamps: by cross-correlating every extracted order with the calibrated,
+  flux-normalised reference lamp spectra `nanshan-thar-{high,mid}res.txt` in
+  `calib_data/telescopes/nanshan12/` (columns: order, wavelength, normalised flux);
+  a lamp matching neither is taken as low resolution;
+- bias frames: by the `high` token in the file name.
+
+Step 1 can crop the images (`trim_x_start/end`, `trim_y_start/end`, DS9 1-based, applied
+after `flip_vertical`; a bound < 1 leaves that side open). Cropped frames are written to
+`step1_basic/cropped/` and used by all later steps; the Nanshan profile keeps rows 600-1300.
+Order tracing drops false traces (`reject_false_traces`): traces leaving the image, crossing
+a neighbour, or bending differently from the neighbouring orders (`curvature_tolerance`).
+`seed_columns` / `side_min_coverage` / `max_search_half` let the tracer find orders visible on
+one side only and follow widely spaced curved orders (used automatically for the low mode).
+`exclude_lowest_apertures` / `exclude_highest_apertures` (`[reduce.trace]`, default 0) skip the
+N lowest / highest traces so noise-only orders are not extracted (set to 1 automatically for the Nanshan low mode).
+
+The initial wavelength solution of the high/mid groups is not obtained from an anchor
+line table: each extracted lamp order is cross-correlated with the reference spectrum
+(giving the order offset and pixel shift), then the full catalog `thar-noao.dat` is
+matched for the final fit. `nanshan-thar-lowres.txt` lists identified lines
+(order, X, wavelength) and is used as an anchor table. Nanshan frames have the
+orders ascending in the opposite vertical sense, so `[data] flip_vertical = yes` flips
+them in Step 1.
+
+**Per-order wavelength fit** (`[reduce.wlcalib] fit_mode = per_order`): by default
+(`global`) one 2D polynomial f(order, x) is fitted to all lines. With `per_order`
+the 2D fit is still made first (outlier rejection, fallback for orders with fewer than
+`order_min_lines` lines or covering less than 60 % of the detector), then every
+well-constrained order is refitted independently with a 1D Chebyshev polynomial of
+degree `order_degree`. The catalog is then rematched with `refine_tolerance` for these
+orders (`refine_iterations` passes) before the final fit.
+
 **Slit mode** (`[telescope] instrument = slit`, used by `MSTG193_slit`): a
 separate single-aperture pipeline (`core/slit_pipeline.py`) replaces the echelle
 stages: overscan/bias → pixel flat → cosmic rays → star trace + sky subtraction →
-sum/optimal extraction → 1-D wavelength solution. Frame types are taken from file
+optimal extraction → 1-D wavelength solution. Frame types are taken from file
 names (`frame_type_source = filename`; bias / flat / FeAr / dark, rest = science).
 Run the red and blue cameras separately (one directory each). Wavelength
-calibration needs `[slit] identification_file` (pixel, wavelength rows; candidate
-pixels are written to `step7_wavelength/<lamp frame>_peaks.csv`) or `wave_start`/`wave_end`
-hints; otherwise spectra are saved on a pixel axis.
+calibration needs `[slit] identification_file` (pixel, wavelength rows; generate it
+with `specproc identify`) or `wave_start`/`wave_end` hints; otherwise
+spectra are saved on a pixel axis.  The final 1-D solution uses
+`[slit] wave_poly_type` (`legendre` by default, `chebyshev` or `polynomial` also
+accepted) and `wave_poly_order` (default 5 when enough well-spread lines are available).
 
 Slit-mode output layout (same numbering as HRS; steps not needed are omitted):
-`step1_basic/{overscan_corrected,bias_subtracted,cosmic_corrected}`, `step2_trace` (slit trace of the master flat: centre and both edges, plus each
-science frame's trace = flat centre line + a constant star offset; the same trace
-is applied to the science and lamp frames),
-`step4_flat_corrected` (master/pixel flat and flat-fielded images), `step5_extraction`
-(sky-subtracted images and 1-D spectra of the targets, every lamp frame and the master flat,
-all extracted along the master-flat trace), `step7_wavelength`. No scattered-light
+`step1_basic/{overscan_corrected,bias_subtracted,cosmic_corrected}` (each FITS image
+has a matching PDF diagnostic plus `master_bias.pdf`), `step2_trace` (independent traces of the master flat, each lamp frame and each
+science frame, with a per-frame `*_trace.txt` and `*_trace.pdf`),`step4_flat_corrected` (master/pixel flat and flat-fielded images), `step5_extraction`
+(sky-subtracted images, 1-D spectra and an extraction-aperture/sky-region
+diagnostic PDF for each science frame, extracted along its own trace),
+`step7_wavelength` (calibrated target and lamp spectra `*_wave.fits`/`*_wave.pdf`,
+residual plots and a two-page `*_arc.pdf` containing the arc spectrum + matched
+lines/residuals and the R(λ) diagnostic). No scattered-light
 (step3) or de-blazing (step6) directories are created.
 
 **Extraction aperture (slit mode)**: with `[slit] aperture_mode = auto` the spatial FWHM of each
@@ -516,8 +583,72 @@ science frame is measured from the profile stacked along the whole dispersion ax
 range (window ±`snr_half_window` px; signal = median flux, noise = standard deviation
 of the residual to a quadratic fit). SNR is a dimensionless ratio, labelled
 `SNR=xx@position`: the position is in pixels before wavelength calibration
-(`step5_extraction/*_spec_pixel.pdf`) and in Å after it (`step7_wavelength/*_spec_wave.pdf`).
-Values are annotated on the plots and stored as `SNRPxx`/`SNRWxx` keywords in the `*_spec.fits` table.
+(`step5_extraction/*_pixel.pdf`) and in Å after it (`step7_wavelength/*_wave.pdf`).
+Values are annotated on the plots and stored as `SNRPxx`/`SNRWxx` keywords in the `*_pixel.fits` / `*_wave.fits` table.
+
+**Anchor lines (slit mode)**: `specproc identify` identifies the emission lines of an
+extracted lamp spectrum against a reference atlas (the NOIRLAB/KPNO FeAr atlas
+`calib_data/linelists/fear.fits` is bundled) or a text line list.  The top panel
+shows the normalized measured lamp spectrum in the upper half (pixel axis on top,
+only peaks above the SNR threshold marked with red inverted triangles) and the
+reference atlas/line list in the lower half (blue, wavelength axis at the bottom);
+the reference is mapped through the current dispersion model.  The
+bottom panel shows the residuals of a Legendre or Chebyshev series fitted to the
+identified lines. The resolving power is estimated from the Gaussian FWHM of the
+clean arc lines, R = λ/FWHM, and is shown in a separate R(λ) tab and in the saved diagnostic PDF. The spectrum panel keeps the pixel axis while the residual panel uses wavelength; the two tabs are saved as two PDF pages. The basis, degree and residual-clip threshold are adjustable in
+the window.  Press
+**Auto identify** to match all strong peaks, adjust the result by hand if needed
+(click a lamp peak, then the matching reference line; right-click removes a line),
+and save.  **Flip x** reverses the displayed pixel axis when wavelength decreases
+with pixel; automatic identification sets it from the fitted dispersion.  Saving
+writes a clean anchor CSV — the first two columns (0-based pixel, wavelength in Å)
+are exactly the `[slit] identification_file` format — plus a diagnostic figure
+(spectrum, zoomed observed/reference overlay and residuals).  The pipeline then
+extends these anchors to the full `full_linelist` catalogue for the final wavelength
+solution.
+
+The final dispersion fit basis is selectable: `--poly-type legendre|chebyshev|polynomial`
+(default `legendre`) and `--poly-order` (default 5, up to 9); the interactive window
+exposes the same basis and degree controls.  The slit pipeline reads
+`[slit] wave_poly_type` and `wave_poly_order`.
+
+The same engine runs headless with `--auto`:
+
+```bash
+# Interactive: reference atlas + measured lamp; adjust by hand, then save.
+specproc identify \
+    --lamp output/step5_extraction/RR2000V_FeAr_0.8silt_0.2s_1_pixel.fits \
+    --ref src/specproc/calib_data/linelists/fear.fits \
+    --linelist  src/specproc/calib_data/linelists/fear.dat \
+    --output    src/specproc/calib_data/telescopes/mstg193slit/mstg193slit_anchors_R.csv \
+    --plot      docs/mstg193slit_R_anchor_match.pdf
+# MSTG arm is read from the FITS header (TELESCOP=MOST and
+# INSTRUME=Camera Spectrum-R/B); --arm B is only an explicit override.
+
+# Fully automatic, no window (same options; writes both files).
+specproc identify --auto --lamp <lamp.fits> --ref <atlas.fits> \
+    --output <ids.csv> --plot <diagnostic.pdf>
+```
+
+`identify` accepts FITS, CSV and TXT inputs. Its residual fit defaults to 3σ clipping based on the inlier RMS; an absolute-Å clipping mode is also available. Anchor and diagnostic outputs default to
+the current working directory (use `--output`/`--plot` to override); anchor CSV columns are
+`pixel, wavelength, snr`. The search scans
+the dispersion curvature and matches the strongest reference lines,
+so it works without manual pairs and without a `wave_start`/`wave_end` hint.  Both
+pixel directions are tried, so a spectrum whose wavelength decreases with pixel is
+matched as well; the window then flips its displayed pixel axis to keep wavelength
+increasing to the right.  In the
+window, any manual pairs seed the solution and the automatic match then extends them.
+Supplying
+`--config` or `--wave-range` only adds a soft preference for that range; it never cuts the
+reference catalogue, so a slightly wrong hint cannot force a wrong alias. For a
+typical RR2000V frame the cubic extrapolates to ≈3976–11677 Å, while the anchors
+themselves span ≈5912–9784 Å; the selected anchors leave ≈0.3 Å residuals. The blue
+extrapolation has been checked against the night-sky spectrum ([OI] 5577/6300/6363,
+Na I and Hα agree within 0.4 Å); the red end beyond 9800 Å remains approximate.
+Always inspect the two-page diagnostic PDF (spectrum/reference match and residuals; R(λ)) before using the file, and re-run the tool if the grating, slit or camera
+focus changes. The reference atlas is matched to the same number of brightest peaks
+as the observed lamp; lower `--min-snr` if the lamp itself has too few strong peaks.
 
 **CLI Workflow**:
 1. Follow prompts to select files
@@ -525,24 +656,58 @@ Values are annotated on the plots and stored as `SNRPxx`/`SNRWxx` keywords in th
 3. Monitor console progress
 4. Check results in output directory
 
+### Command-line tools (not part of the pipeline)
+
+SpecProc also ships a few small, self-contained commands for preparing and
+inspecting data. They are not part of the reduction pipeline. Each one is
+invoked as a standalone `specproc.<tool>` command (type `specproc.` and press
+Tab to list all three; `specproc <tool> ...` also works):
+
+| Command | Purpose |
+|---|---|
+| `specproc.air2vac INPUT OUTPUT` | Convert line-list wavelengths from air to vacuum (Å) |
+| `specproc.vac2air INPUT OUTPUT` | Convert line-list wavelengths from vacuum to air (Å) |
+| `specproc.identify` | Interactive/automatic lamp-line identification: reference atlas + lamp spectrum → anchor CSV + diagnostic figure |
+| `specproc tools` | List the tools above |
+
+Run `specproc <tool> --help` for the full option list; `specproc --help` also
+lists the available tools. If the first argument names an existing file or
+directory it is always treated as pipeline input, so a data directory is never
+mistaken for a tool.
+
+**Shell completion** (completes tool names, their options and choice values;
+positional file arguments fall back to the shell's filename completion):
+
+```bash
+# bash: add to ~/.bashrc
+eval "$(specproc --completion bash)"
+
+# zsh: add to ~/.zshrc
+eval "$(specproc --completion zsh)"
+```
+
 ## Calibration Data
 
 ### Directory Structure
 
-```
+Calibration data ships with the package under `src/specproc/calib_data/`:
+
+```text
 calib_data/
-├── linelists/              # Lamp emission line catalogs
-│   ├── thar-noao.dat      # ThAr lamp lines (Xinglong 2.16m HRS recommended)
-│   ├── thar.dat           # Standard ThAr lamp lines
-│   ├── FeAr.dat           # FeAr lamp lines
-└── ...
-└── telescopes/             # Telescope-specific calibration files
-    ├── generic/           # Generic configuration template
-    └── xinglong216hrs/    # Xinglong 2.16m telescope
-        ├── wlcalib_20141103049.fits
-        ├── wlcalib_20171202012.fits
-        ├── wlcalib_20190905028_A.fits
-        └── wlcalib_20211123011_A.fits
+├── linelists/                  # Lamp emission line lists / atlases
+│   ├── thar-noao.dat           # ThAr lamp lines (Xinglong 2.16m HRS recommended)
+│   ├── thar.dat                # Standard ThAr lamp lines
+│   ├── fear.dat                # FeAr lamp line list (Willmarth)
+│   ├── fear.fits               # NOIRLAB/KPNO FeAr atlas spectrum (used by `specproc identify`)
+│   ├── argon.dat / xenon.dat / krypton.dat / thorium.dat
+│   └── skylines.dat / ohline.dat and other auxiliary lists
+└── telescopes/                 # Telescope-specific calibration files
+    ├── generic/                # Generic configuration template
+    ├── xinglong216hrs/         # Xinglong 2.16m HRS: xinglong216_thar_anchors.csv
+    ├── xinglong216bfosc/       # Xinglong 2.16m BFOSC
+    ├── lijiang24hrs/           # Lijiang 2.4m HRS: lijiang24_hrs_thar_anchors.csv
+    ├── mstg193slit/            # Muztagh-Ata 1.93m slit: mstg193slit_anchors_{R,B}.csv
+    └── nanshan12/              # Nanshan 1.2m fibre: nanshan-thar-{high,mid,low}res.txt
 ```
 
 ### Lamp Line Lists
@@ -550,7 +715,8 @@ calib_data/
 **Available linelist files**:
 - `thar-noao.dat` - ThAr lamp lines (Xinglong 2.16m HRS recommended)
 - `thar.dat` - Standard ThAr lamp lines
-- `FeAr.dat` - FeAr lamp lines
+- `fear.dat` - FeAr lamp lines (Willmarth 3000-10,000 Å)
+- `fear.fits` - NOIRLAB/KPNO FeAr atlas spectrum used by `specproc identify`
 
 **Supported lamp types**:
 - `ThAr` - Thorium-Argon (most common for echelle spectrographs)
@@ -562,11 +728,15 @@ calib_data/
 
 ### Telescope Calibrations
 
-**Available calibration files for Xinglong 2.16m HRS**:
-- `wlcalib_20141103049.fits` - 2014-11-03 04:50
-- `wlcalib_20171202012.fits` - 2017-12-02 01:20
-- `wlcalib_20190905028_A.fits` - 2019-09-05 02:50 (version A)
-- `wlcalib_20211123011_A.fits` - 2021-11-23 01:10 (version A) - **Latest**
+Each telescope directory holds the **anchor tables** (already-identified pixel/wavelength
+pairs) plus the matching identification notes:
+
+| Telescope | Files |
+|---|---|
+| Xinglong 2.16m HRS | `xinglong216_thar_anchors.csv` (+ 216HRS lamp identification PDF) |
+| Lijiang 2.4m HRS | `lijiang24_hrs_thar_anchors.csv` (+ Lijiang 2.4m lamp calibration PDF) |
+| Muztagh-Ata 1.93m slit | `mstg193slit_anchors_R.csv` / `mstg193slit_anchors_B.csv` (each with a PDF) |
+| Nanshan 1.2m fibre | `nanshan-thar-highres.txt` / `-medres.txt` / `-lowres.txt` (order, wavelength, normalised flux) |
 
 ### Configuration
 
@@ -579,9 +749,8 @@ instrument = hrs
 linelist_type = ThAr
 linelist_path = calib_data/linelists/
 linelist_file = thar-noao.dat
-use_precomputed_calibration = yes
-calibration_path = calib_data/telescopes/xinglong216hrs/
-calibration_file = wlcalib_20211123011_A.fits
+full_linelist = calib_data/linelists/thar-noao.dat
+anchor_file = calib_data/telescopes/xinglong216hrs/xinglong216_thar_anchors.csv
 ```
 
 ## Troubleshooting
@@ -619,35 +788,34 @@ cp /path/to/SpecProc/src/specproc/config/default_config.cfg ./specproc.cfg
 
 ## Documentation
 
-- See [calib_data/README.md](calib_data/README.md) for calibration data configuration
-- See [README_CN.md](README_CN.md) for Chinese documentation
-- See [PIPELINE_FLOWCHART.md](PIPELINE_FLOWCHART.md) for detailed processing workflow
+- See [README_CN.md](README_CN.md) for the Chinese documentation（中文文档）
+- See [calib_data/README.md](src/specproc/calib_data/README.md) for calibration data configuration
+- See [docs/](docs/) for screenshots and software evaluation reports
 
 ## Project Structure
 
 ```
 SpecProc/
 ├── README.md                    # Main documentation
-├── README_CN.md                # Main documentation (Chinese)
-├── specproc.cfg.example         # Example user configuration
+├── pyproject.toml               # Packaging and console-script entry points
 ├── install.sh                   # Installation script
-├── requirements.txt              # Python dependencies
-├── run.py                      # Main entry point
-├── setup.py                     # Installation configuration
 ├── LICENSE                      # License
-├── .gitignore                  # Git ignore rules
-├── src/
-│   └── specproc/               # Source code
-│       ├── calib_data/              # Calibration data
-│       │   ├── linelists/
-│       │   └── telescopes/
-│       ├── default_config.cfg       # Default configuration
-│       ├── gui/                     # GUI modules
-│       ├── core/                    # Core processing
-│       ├── config/                  # Configuration management
-│       ├── utils/                   # Utility functions
-│       └── plotting/                # Plotting functions
-└── test_*.py                    # Test files
+├── .gitignore                   # Git ignore rules
+├── docs/                        # Screenshots, reports and the Chinese manual
+├── tests/                       # pytest tests
+└── src/
+    └── specproc/                # Source code
+        ├── calib_data/          # Calibration data (line lists, telescope profiles)
+        ├── config/              # Configuration management & default configs
+        ├── core/                # Reduction pipeline (echelle and long-slit)
+        ├── gui/                 # Main GUI (main window, settings dialog)
+        ├── plotting/            # Plotting helpers
+        ├── utils/               # Shared helpers + standalone CLI tools
+        │   ├── airvac.py        #   air <-> vacuum wavelength conversion
+        │   ├── identify.py      #   interactive/automatic line identification (`specproc identify`)
+        │   ├── tool_registry.py #   registry behind `specproc tools`
+        │   └── completion.py    #   bash/zsh completion support
+        └── main.py              # `specproc` entry point (GUI + CLI + tools)
 ```
 
 ## License