head	8.7;
access;
symbols;
locks; strict;
comment	@ * @;


8.7
date	2026.05.11.12.01.10;	author mcalabre;	state Exp;
branches;
next	8.6;

8.6
date	2026.03.29.13.53.56;	author mcalabre;	state Exp;
branches
	8.6.1.1;
next	8.5;

8.5
date	2025.12.06.13.47.41;	author mcalabre;	state Exp;
branches
	8.5.1.1;
next	8.4;

8.4
date	2024.10.28.13.56.16;	author mcalabre;	state Exp;
branches
	8.4.1.1;
next	8.3;

8.3
date	2024.05.13.16.33.00;	author mcalabre;	state Exp;
branches
	8.3.1.1;
next	8.2;

8.2
date	2023.11.16.10.00.29;	author mcalabre;	state Exp;
branches
	8.2.1.1;
next	8.1;

8.1
date	2023.07.05.17.12.07;	author mcalabre;	state Exp;
branches
	8.1.1.1;
next	8.0;

8.0
date	2023.07.01.06.15.04;	author mcalabre;	state Exp;
branches
	8.0.1.1;
next	7.13;

7.13
date	2022.10.07.03.43.35;	author mcalabre;	state Exp;
branches
	7.13.1.1;
next	7.12;

7.12
date	2022.09.09.04.57.58;	author mcalabre;	state Exp;
branches
	7.12.1.1;
next	7.11;

7.11
date	2022.04.26.06.13.52;	author mcalabre;	state Exp;
branches
	7.11.1.1;
next	7.10;

7.10
date	2022.04.23.14.25.15;	author mcalabre;	state Exp;
branches
	7.10.1.1;
next	7.9;

7.9
date	2022.03.25.15.14.48;	author mcalabre;	state Exp;
branches
	7.9.1.1;
next	7.8;

7.8
date	2022.03.25.06.11.49;	author mcalabre;	state Exp;
branches
	7.8.1.1;
next	7.7;

7.7
date	2021.07.12.06.36.49;	author mcalabre;	state Exp;
branches
	7.7.1.1;
next	7.6;

7.6
date	2021.04.13.12.57.01;	author mcalabre;	state Exp;
branches
	7.6.1.1;
next	7.5;

7.5
date	2021.03.20.05.54.58;	author mcalabre;	state Exp;
branches
	7.5.1.1;
next	7.4;

7.4
date	2021.01.31.02.24.51;	author mcalabre;	state Exp;
branches
	7.4.1.1;
next	7.3;

7.3
date	2020.06.03.03.37.02;	author mcalabre;	state Exp;
branches
	7.3.1.1;
next	7.2;

7.2
date	2020.03.09.07.31.23;	author mcalabre;	state Exp;
branches
	7.2.1.1;
next	7.1;

7.1
date	2019.12.31.13.25.19;	author mcalabre;	state Exp;
branches
	7.1.1.1;
next	6.4;

6.4
date	2019.08.15.09.30.18;	author mcalabre;	state Exp;
branches
	6.4.1.1;
next	6.3;

6.3
date	2019.07.12.07.33.39;	author mcalabre;	state Exp;
branches
	6.3.1.1;
next	6.2;

6.2
date	2018.10.20.10.03.13;	author mcalabre;	state Exp;
branches
	6.2.1.1;
next	6.1;

6.1
date	2018.10.19.08.35.17;	author mcalabre;	state Exp;
branches
	6.1.1.1;
next	5.20;

5.20
date	2018.10.05.05.32.41;	author mcalabre;	state Exp;
branches
	5.20.1.1;
next	5.19;

5.19
date	2018.07.26.15.37.04;	author mcalabre;	state Exp;
branches
	5.19.1.1;
next	5.18;

5.18
date	2018.01.10.08.32.14;	author mcalabre;	state Exp;
branches
	5.18.1.1;
next	5.17;

5.17
date	2017.09.18.08.44.23;	author mcalabre;	state Exp;
branches
	5.17.1.1;
next	5.16;

5.16
date	2017.01.15.04.25.01;	author mcalabre;	state Exp;
branches
	5.16.1.1;
next	5.15;

5.15
date	2016.04.05.12.55.10;	author mcalabre;	state Exp;
branches
	5.15.1.1;
next	5.14;

5.14
date	2016.02.07.10.49.31;	author mcalabre;	state Exp;
branches
	5.14.1.1;
next	5.13;

5.13
date	2016.01.26.08.51.13;	author mcalabre;	state Exp;
branches
	5.13.1.1;
next	5.12;

5.12
date	2015.11.15.02.13.00;	author mcalabre;	state Exp;
branches
	5.12.1.1;
next	5.11;

5.11
date	2015.10.18.09.13.05;	author mcalabre;	state Exp;
branches
	5.11.1.1;
next	5.10;

5.10
date	2015.10.09.08.19.15;	author mcalabre;	state Exp;
branches
	5.10.1.1;
next	5.9;

5.9
date	2015.07.21.09.20.01;	author mcalabre;	state Exp;
branches
	5.9.1.1;
next	5.8;

5.8
date	2015.07.08.11.03.59;	author mcalabre;	state Exp;
branches
	5.8.1.1;
next	5.7;

5.7
date	2015.06.29.02.44.16;	author mcalabre;	state Exp;
branches
	5.7.1.1;
next	5.6;

5.6
date	2015.06.14.07.11.24;	author mcalabre;	state Exp;
branches
	5.6.1.1;
next	5.5;

5.5
date	2015.05.05.13.16.31;	author mcalabre;	state Exp;
branches
	5.5.1.1;
next	5.4;

5.4
date	2015.04.21.14.41.05;	author mcalabre;	state Exp;
branches
	5.4.1.1;
next	5.3;

5.3
date	2015.04.21.02.50.51;	author mcalabre;	state Exp;
branches
	5.3.1.1;
next	5.2;

5.2
date	2015.04.15.12.35.07;	author mcalabre;	state Exp;
branches
	5.2.1.1;
next	5.1;

5.1
date	2015.04.07.10.56.36;	author mcalabre;	state Exp;
branches
	5.1.1.1;
next	5.0;

5.0
date	2015.04.05.12.24.59;	author mcalabre;	state Exp;
branches
	5.0.1.1;
next	4.25;

4.25
date	2014.12.14.14.29.36;	author mcalabre;	state Exp;
branches
	4.25.1.1;
next	4.24;

4.24
date	2014.09.18.15.25.00;	author mcalabre;	state Exp;
branches
	4.24.1.1;
next	4.23;

4.23
date	2014.05.13.05.50.51;	author mcalabre;	state Exp;
branches
	4.23.1.1;
next	4.22;

4.22
date	2014.04.12.15.03.52;	author mcalabre;	state Exp;
branches
	4.22.1.1;
next	4.21;

4.21
date	2014.03.24.05.12.27;	author mcalabre;	state Exp;
branches
	4.21.1.1;
next	4.20;

4.20
date	2013.12.18.05.42.49;	author mcalabre;	state Exp;
branches
	4.20.1.1;
next	4.19;

4.19
date	2013.09.29.14.17.51;	author mcalabre;	state Exp;
branches
	4.19.1.1;
next	4.18;

4.18
date	2013.07.13.10.00.04;	author mcalabre;	state Exp;
branches
	4.18.1.1;
next	4.17;

4.17
date	2013.01.29.05.29.20;	author cal103;	state Exp;
branches
	4.17.1.1;
next	4.16;

4.16
date	2012.11.07.04.42.44;	author cal103;	state Exp;
branches
	4.16.1.1;
next	4.15;

4.15
date	2012.09.26.14.26.05;	author cal103;	state Exp;
branches
	4.15.1.1;
next	4.14;

4.14
date	2012.07.13.10.02.27;	author cal103;	state Exp;
branches
	4.14.1.1;
next	4.13;

4.13
date	2012.03.14.07.39.30;	author cal103;	state Exp;
branches
	4.13.1.1;
next	4.12;

4.12
date	2012.02.29.07.57.56;	author cal103;	state Exp;
branches
	4.12.1.1;
next	4.11;

4.11
date	2012.02.20.23.30.02;	author cal103;	state Exp;
branches
	4.11.1.1;
next	4.10;

4.10
date	2012.02.05.23.41.44;	author cal103;	state Exp;
branches
	4.10.1.1;
next	4.9;

4.9
date	2012.01.24.05.40.29;	author cal103;	state Exp;
branches
	4.9.1.1;
next	4.8;

4.8
date	2011.08.15.08.05.53;	author cal103;	state Exp;
branches
	4.8.1.1;
next	4.7;

4.7
date	2011.02.07.07.03.42;	author cal103;	state Exp;
branches
	4.7.1.1;
next	4.6;

4.6
date	2010.11.16.06.15.31;	author cal103;	state Exp;
branches
	4.6.1.1;
next	4.5;

4.5
date	2010.07.16.07.01.25;	author cal103;	state Exp;
branches
	4.5.1.1;
next	4.4;

4.4
date	2009.08.06.07.41.33;	author cal103;	state Exp;
branches
	4.4.1.1;
next	4.3;

4.3
date	2007.12.27.05.41.36;	author cal103;	state Exp;
branches
	4.3.1.1;
next	4.2;

4.2
date	2005.09.22.08.53.12;	author cal103;	state Exp;
branches
	4.2.1.1;
next	4.1;

4.1
date	2005.08.28.06.17.40;	author cal103;	state Exp;
branches;
next	4.0;

4.0
date	2005.02.04.06.15.26;	author cal103;	state Exp;
branches;
next	3.6;

3.6
date	2004.08.25.04.59.52;	author cal103;	state Exp;
branches;
next	3.5;

3.5
date	2004.06.28.04.23.46;	author mcalabre;	state Exp;
branches;
next	0.0;

0.0
date	2004.06.28.04.22.19;	author mcalabre;	state Exp;
branches;
next	;

4.2.1.1
date	2005.12.05.02.39.43;	author cal103;	state Exp;
branches;
next	4.2.1.2;

4.2.1.2
date	2006.08.02.00.14.58;	author cal103;	state Exp;
branches;
next	4.2.1.3;

4.2.1.3
date	2007.07.12.00.24.11;	author cal103;	state Exp;
branches;
next	4.2.1.4;

4.2.1.4
date	2007.07.27.08.47.26;	author cal103;	state Exp;
branches;
next	4.2.1.5;

4.2.1.5
date	2007.08.01.08.21.23;	author cal103;	state Exp;
branches;
next	4.2.1.6;

4.2.1.6
date	2007.12.04.01.50.10;	author cal103;	state Exp;
branches;
next	4.2.1.7;

4.2.1.7
date	2007.12.04.03.11.40;	author cal103;	state Exp;
branches;
next	4.2.1.8;

4.2.1.8
date	2007.12.04.04.04.05;	author cal103;	state Exp;
branches;
next	4.2.1.9;

4.2.1.9
date	2007.12.04.04.16.17;	author cal103;	state Exp;
branches;
next	4.2.1.10;

4.2.1.10
date	2007.12.04.04.21.41;	author cal103;	state Exp;
branches;
next	4.2.1.11;

4.2.1.11
date	2007.12.04.04.59.09;	author cal103;	state Exp;
branches;
next	4.2.1.12;

4.2.1.12
date	2007.12.26.04.20.03;	author cal103;	state Exp;
branches;
next	4.2.1.13;

4.2.1.13
date	2007.12.27.05.15.55;	author cal103;	state Exp;
branches;
next	;

4.3.1.1
date	2007.12.27.13.23.47;	author cal103;	state Exp;
branches;
next	4.3.1.2;

4.3.1.2
date	2008.04.02.06.17.13;	author cal103;	state Exp;
branches;
next	4.3.1.3;

4.3.1.3
date	2009.07.22.05.10.07;	author cal103;	state Exp;
branches;
next	;

4.4.1.1
date	2009.08.10.08.52.49;	author cal103;	state Exp;
branches;
next	4.4.1.2;

4.4.1.2
date	2010.01.19.03.42.50;	author cal103;	state Exp;
branches;
next	4.4.1.3;

4.4.1.3
date	2010.07.07.07.34.29;	author cal103;	state Exp;
branches;
next	;

4.5.1.1
date	2010.07.16.07.05.31;	author cal103;	state Exp;
branches;
next	;

4.6.1.1
date	2010.11.16.06.16.19;	author cal103;	state Exp;
branches;
next	4.6.1.2;

4.6.1.2
date	2011.01.14.06.33.16;	author cal103;	state Exp;
branches;
next	;

4.7.1.1
date	2011.02.07.07.04.22;	author cal103;	state Exp;
branches;
next	4.7.1.2;

4.7.1.2
date	2011.07.21.03.48.09;	author cal103;	state Exp;
branches;
next	4.7.1.3;

4.7.1.3
date	2011.08.09.02.43.50;	author cal103;	state Exp;
branches;
next	4.7.1.4;

4.7.1.4
date	2011.08.10.06.27.02;	author cal103;	state Exp;
branches;
next	;

4.8.1.1
date	2011.08.15.08.07.06;	author cal103;	state Exp;
branches;
next	4.8.1.2;

4.8.1.2
date	2012.01.24.05.23.06;	author cal103;	state Exp;
branches;
next	;

4.9.1.1
date	2012.01.24.05.41.45;	author cal103;	state Exp;
branches;
next	;

4.10.1.1
date	2012.02.05.23.42.46;	author cal103;	state Exp;
branches;
next	;

4.11.1.1
date	2012.02.20.23.31.13;	author cal103;	state Exp;
branches;
next	;

4.12.1.1
date	2012.02.29.07.59.10;	author cal103;	state Exp;
branches;
next	;

4.13.1.1
date	2012.03.14.07.40.37;	author cal103;	state Exp;
branches;
next	4.13.1.2;

4.13.1.2
date	2012.07.13.03.34.20;	author cal103;	state Exp;
branches;
next	;

4.14.1.1
date	2012.07.13.10.04.44;	author cal103;	state Exp;
branches;
next	;

4.15.1.1
date	2012.09.26.14.27.51;	author cal103;	state Exp;
branches;
next	;

4.16.1.1
date	2012.11.07.04.45.56;	author cal103;	state Exp;
branches;
next	4.16.1.2;

4.16.1.2
date	2013.01.29.03.44.31;	author cal103;	state Exp;
branches;
next	;

4.17.1.1
date	2013.01.29.05.32.32;	author cal103;	state Exp;
branches;
next	;

4.18.1.1
date	2013.07.13.10.02.37;	author mcalabre;	state Exp;
branches;
next	;

4.19.1.1
date	2013.09.29.14.20.38;	author mcalabre;	state Exp;
branches;
next	;

4.20.1.1
date	2013.12.18.05.46.55;	author mcalabre;	state Exp;
branches;
next	4.20.1.2;

4.20.1.2
date	2014.03.21.06.32.19;	author mcalabre;	state Exp;
branches;
next	;

4.21.1.1
date	2014.03.24.05.15.28;	author mcalabre;	state Exp;
branches;
next	;

4.22.1.1
date	2014.04.12.15.06.32;	author mcalabre;	state Exp;
branches;
next	;

4.23.1.1
date	2014.05.13.05.53.49;	author mcalabre;	state Exp;
branches;
next	;

4.24.1.1
date	2014.09.18.15.28.09;	author mcalabre;	state Exp;
branches;
next	;

4.25.1.1
date	2014.12.14.14.32.45;	author mcalabre;	state Exp;
branches;
next	4.25.1.2;

4.25.1.2
date	2015.01.06.01.01.06;	author mcalabre;	state Exp;
branches;
next	4.25.1.3;

4.25.1.3
date	2015.03.15.08.47.22;	author mcalabre;	state Exp;
branches;
next	4.25.1.4;

4.25.1.4
date	2015.04.05.06.38.51;	author mcalabre;	state Exp;
branches;
next	;

5.0.1.1
date	2015.04.05.12.28.00;	author mcalabre;	state Exp;
branches;
next	;

5.1.1.1
date	2015.04.07.11.01.10;	author mcalabre;	state Exp;
branches;
next	5.1.1.2;

5.1.1.2
date	2015.04.13.08.28.38;	author mcalabre;	state Exp;
branches;
next	;

5.2.1.1
date	2015.04.15.12.39.14;	author mcalabre;	state Exp;
branches;
next	;

5.3.1.1
date	2015.04.21.02.54.02;	author mcalabre;	state Exp;
branches;
next	;

5.4.1.1
date	2015.04.21.14.44.28;	author mcalabre;	state Exp;
branches;
next	5.4.1.2;

5.4.1.2
date	2015.04.23.11.03.11;	author mcalabre;	state Exp;
branches;
next	;

5.5.1.1
date	2015.05.05.13.21.00;	author mcalabre;	state Exp;
branches;
next	;

5.6.1.1
date	2015.06.14.07.14.44;	author mcalabre;	state Exp;
branches;
next	;

5.7.1.1
date	2015.06.29.02.47.24;	author mcalabre;	state Exp;
branches;
next	;

5.8.1.1
date	2015.07.08.11.07.18;	author mcalabre;	state Exp;
branches;
next	;

5.9.1.1
date	2015.07.21.09.28.07;	author mcalabre;	state Exp;
branches;
next	;

5.10.1.1
date	2015.10.09.08.22.35;	author mcalabre;	state Exp;
branches;
next	;

5.11.1.1
date	2015.10.18.09.16.27;	author mcalabre;	state Exp;
branches;
next	;

5.12.1.1
date	2015.11.15.02.16.14;	author mcalabre;	state Exp;
branches;
next	5.12.1.2;

5.12.1.2
date	2016.01.25.05.17.04;	author mcalabre;	state Exp;
branches;
next	5.12.1.3;

5.12.1.3
date	2016.01.26.08.09.41;	author mcalabre;	state Exp;
branches;
next	;

5.13.1.1
date	2016.01.26.08.54.32;	author mcalabre;	state Exp;
branches;
next	;

5.14.1.1
date	2016.02.07.10.52.44;	author mcalabre;	state Exp;
branches;
next	;

5.15.1.1
date	2016.04.05.12.58.35;	author mcalabre;	state Exp;
branches;
next	5.15.1.2;

5.15.1.2
date	2017.01.15.04.14.00;	author mcalabre;	state Exp;
branches;
next	;

5.16.1.1
date	2017.01.15.04.28.59;	author mcalabre;	state Exp;
branches;
next	;

5.17.1.1
date	2017.09.18.08.45.59;	author mcalabre;	state Exp;
branches;
next	5.17.1.2;

5.17.1.2
date	2018.01.10.08.25.34;	author mcalabre;	state Exp;
branches;
next	;

5.18.1.1
date	2018.01.10.08.33.04;	author mcalabre;	state Exp;
branches;
next	;

5.19.1.1
date	2018.07.26.15.41.40;	author mcalabre;	state Exp;
branches;
next	;

5.20.1.1
date	2018.10.05.05.33.33;	author mcalabre;	state Exp;
branches;
next	5.20.1.2;

5.20.1.2
date	2018.10.19.07.28.12;	author mcalabre;	state Exp;
branches;
next	;

6.1.1.1
date	2018.10.19.08.36.15;	author mcalabre;	state Exp;
branches;
next	6.1.1.2;

6.1.1.2
date	2018.10.20.09.38.53;	author mcalabre;	state Exp;
branches;
next	;

6.2.1.1
date	2018.10.20.10.04.15;	author mcalabre;	state Exp;
branches;
next	6.2.1.2;

6.2.1.2
date	2019.05.10.01.56.50;	author mcalabre;	state Exp;
branches;
next	6.2.1.3;

6.2.1.3
date	2019.07.11.05.05.59;	author mcalabre;	state Exp;
branches;
next	;

6.3.1.1
date	2019.07.12.07.34.37;	author mcalabre;	state Exp;
branches;
next	;

6.4.1.1
date	2019.08.15.09.31.29;	author mcalabre;	state Exp;
branches;
next	6.4.1.2;

6.4.1.2
date	2019.12.31.03.28.03;	author mcalabre;	state Exp;
branches;
next	;

7.1.1.1
date	2019.12.31.13.28.19;	author mcalabre;	state Exp;
branches;
next	;

7.2.1.1
date	2020.03.09.07.34.50;	author mcalabre;	state Exp;
branches;
next	7.2.1.2;

7.2.1.2
date	2020.06.02.08.50.07;	author mcalabre;	state Exp;
branches;
next	;

7.3.1.1
date	2020.06.03.03.38.10;	author mcalabre;	state Exp;
branches;
next	7.3.1.2;

7.3.1.2
date	2020.08.17.11.19.09;	author mcalabre;	state Exp;
branches;
next	7.3.1.3;

7.3.1.3
date	2021.01.19.14.09.10;	author mcalabre;	state Exp;
branches;
next	7.3.1.4;

7.3.1.4
date	2021.01.28.12.29.30;	author mcalabre;	state Exp;
branches;
next	7.3.1.5;

7.3.1.5
date	2021.01.29.11.36.26;	author mcalabre;	state Exp;
branches;
next	;

7.4.1.1
date	2021.01.31.02.26.24;	author mcalabre;	state Exp;
branches;
next	;

7.5.1.1
date	2021.03.20.05.56.42;	author mcalabre;	state Exp;
branches;
next	;

7.6.1.1
date	2021.04.13.13.00.35;	author mcalabre;	state Exp;
branches;
next	;

7.7.1.1
date	2021.07.12.06.38.27;	author mcalabre;	state Exp;
branches;
next	7.7.1.2;

7.7.1.2
date	2022.03.25.06.05.59;	author mcalabre;	state Exp;
branches;
next	;

7.8.1.1
date	2022.03.25.06.14.14;	author mcalabre;	state Exp;
branches;
next	;

7.9.1.1
date	2022.03.25.15.16.40;	author mcalabre;	state Exp;
branches;
next	7.9.1.2;

7.9.1.2
date	2022.04.22.14.10.34;	author mcalabre;	state Exp;
branches;
next	;

7.10.1.1
date	2022.04.23.14.26.54;	author mcalabre;	state Exp;
branches;
next	;

7.11.1.1
date	2022.04.26.06.15.32;	author mcalabre;	state Exp;
branches;
next	;

7.12.1.1
date	2022.09.09.05.00.36;	author mcalabre;	state Exp;
branches;
next	;

7.13.1.1
date	2022.10.07.03.45.47;	author mcalabre;	state Exp;
branches;
next	7.13.1.2;

7.13.1.2
date	2023.06.15.04.17.19;	author mcalabre;	state Exp;
branches;
next	;

8.0.1.1
date	2023.07.01.06.22.44;	author mcalabre;	state Exp;
branches;
next	;

8.1.1.1
date	2023.07.05.17.15.00;	author mcalabre;	state Exp;
branches;
next	;

8.2.1.1
date	2023.11.16.10.05.57;	author mcalabre;	state Exp;
branches;
next	8.2.1.2;

8.2.1.2
date	2024.04.02.14.01.58;	author mcalabre;	state Exp;
branches;
next	;

8.3.1.1
date	2024.05.13.16.35.39;	author mcalabre;	state Exp;
branches;
next	;

8.4.1.1
date	2024.10.28.13.58.41;	author mcalabre;	state Exp;
branches;
next	8.4.1.2;

8.4.1.2
date	2025.12.06.13.37.16;	author mcalabre;	state Exp;
branches;
next	;

8.5.1.1
date	2025.12.06.14.05.15;	author mcalabre;	state Exp;
branches;
next	8.5.1.2;

8.5.1.2
date	2026.03.29.13.36.16;	author mcalabre;	state Exp;
branches;
next	;

8.6.1.1
date	2026.03.29.14.19.26;	author mcalabre;	state Exp;
branches;
next	;


desc
@Header file and usage notes for the FITS WCS header parsing routines.
@


8.7
log
@WCSLIB 8.7
@
text
@/*============================================================================
  WCSLIB 8.7 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2026, Mark Calabretta

  This file is part of WCSLIB.

  WCSLIB is free software: you can redistribute it and/or modify it under the
  terms of the GNU Lesser General Public License as published by the Free
  Software Foundation, either version 3 of the License, or (at your option)
  any later version.

  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
  more details.

  You should have received a copy of the GNU Lesser General Public License
  along with WCSLIB.  If not, see http://www.gnu.org/licenses.

  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
  http://www.atnf.csiro.au/computing/software/wcs
  $Id: wcshdr.h,v 8.6.1.1 2026/03/29 14:19:26 mcalabre Exp mcalabre $
*=============================================================================
*
* WCSLIB 8.7 - C routines that implement the FITS World Coordinate System
* (WCS) standard.  Refer to the README file provided with WCSLIB for an
* overview of the library.
*
*
* Summary of the wcshdr routines
* ------------------------------
* Routines in this suite are aimed at extracting WCS information from a FITS
* file.  The information is encoded via keywords defined in
*
=   "Representations of world coordinates in FITS",
=   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
=
=   "Representations of celestial coordinates in FITS",
=   Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (WCS Paper II)
=
=   "Representations of spectral coordinates in FITS",
=   Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
=   2006, A&A, 446, 747 (WCS Paper III)
=
=   "Representations of distortions in FITS world coordinate systems",
=   Calabretta, M.R. et al. (WCS Paper IV, draft dated 2004/04/22),
=   available from http://www.atnf.csiro.au/computing/software/wcs
=
=   "Representations of time coordinates in FITS -
=    Time and relative dimension in space",
=   Rots, A.H., Bunclark, P.S., Calabretta, M.R., Allen, S.L.,
=   Manchester, R.N., & Thompson, W.T. 2015, A&A, 574, A36 (WCS Paper VII)
*
* These routines provide the high-level interface between the FITS file and
* the WCS coordinate transformation routines.
*
* Additionally, function wcshdo() is provided to write out the contents of a
* wcsprm struct as a FITS header.
*
* Briefly, the anticipated sequence of operations is as follows:
*
*   - 1: Open the FITS file and read the image or binary table header, e.g.
*        using CFITSIO routine fits_hdr2str().
*
*   - 2: Parse the header using wcspih() or wcsbth(); they will automatically
*        interpret 'TAB' header keywords using wcstab().
*
*   - 3: Allocate memory for, and read 'TAB' arrays from the binary table
*        extension, e.g. using CFITSIO routine fits_read_wcstab() - refer to
*        the prologue of getwcstab.h.  wcsset() will automatically take
*        control of this allocated memory, in particular causing it to be
*        freed by wcsfree().
*
*   - 4: Translate non-standard WCS usage using wcsfix(), see wcsfix.h.
*
*   - 5: Initialize wcsprm struct(s) using wcsset() and calculate coordinates
*        using wcsp2s() and/or wcss2p().  Refer to the prologue of wcs.h for a
*        description of these and other high-level WCS coordinate
*        transformation routines.
*
*   - 6: Clean up by freeing memory with wcsvfree().
*
* In detail:
*
* - wcspih() is a high-level FITS WCS routine that parses an image header.  It
*   returns an array of up to 27 wcsprm structs on each of which it invokes
*   wcstab().
*
* - wcsbth() is the analogue of wcspih() for use with binary tables; it
*   handles image array and pixel list keywords.  As an extension of the FITS
*   WCS standard, it also recognizes image header keywords which may be used
*   to provide default values via an inheritance mechanism.
*
* - wcstab() assists in filling in members of the wcsprm struct associated
*   with coordinate lookup tables ('TAB').  These are based on arrays stored
*   in a FITS binary table extension (BINTABLE) that are located by PVi_ma
*   keywords in the image header.
*
* - wcsidx() and wcsbdx() are utility routines that return the index for a
*   specified alternate coordinate descriptor in the array of wcsprm structs
*   returned by wcspih() or wcsbth().
*
* - wcsvfree() deallocates memory for an array of wcsprm structs, such as
*   returned by wcspih() or wcsbth().
*
* - wcshdo() writes out a wcsprm struct as a FITS header.
*
*
* wcspih() - FITS WCS parser routine for image headers
* ----------------------------------------------------
* wcspih() is a high-level FITS WCS routine that parses an image header,
* either that of a primary HDU or of an image extension.  All WCS keywords
* defined in Papers I, II, III, IV, and VII are recognized, and also those
* used by the AIPS convention and certain other keywords that existed in early
* drafts of the WCS papers as explained in wcsbth() note 5.  wcspih() also
* handles keywords associated with non-standard distortion functions described
* in the prologue of dis.h.
*
* Given a character array containing a FITS image header, wcspih() identifies
* and reads all WCS keywords for the primary coordinate representation and up
* to 26 alternate representations.  It returns this information as an array of
* wcsprm structs.
*
* wcspih() invokes wcstab() on each of the wcsprm structs that it returns.
*
* Use wcsbth() in preference to wcspih() for FITS headers of unknown type;
* wcsbth() can parse image headers as well as binary table and pixel list
* headers, although it cannot handle keywords relating to distortion
* functions, which may only exist in an image header (primary or extension).
*
* Given and returned:
*   header    char[]    Character array containing the (entire) FITS image
*                       header from which to identify and construct the
*                       coordinate representations, for example, as might be
*                       obtained conveniently via the CFITSIO routine
*                       fits_hdr2str().
*
*                       Each header "keyrecord" (formerly "card image")
*                       consists of exactly 80 7-bit ASCII printing characters
*                       in the range 0x20 to 0x7e (which excludes NUL, BS,
*                       TAB, LF, FF and CR) especially noting that the
*                       keyrecords are NOT null-terminated.
*
*                       For negative values of ctrl (see below), header[] is
*                       modified so that WCS keyrecords processed by wcspih()
*                       are removed from it.
*
* Given:
*   nkeyrec   int       Number of keyrecords in header[].
*
*   relax     int       Degree of permissiveness:
*                         0: Recognize only FITS keywords defined by the
*                            published WCS standard.
*                         WCSHDR_all: Admit all recognized informal
*                            extensions of the WCS standard.
*                       Fine-grained control of the degree of permissiveness
*                       is also possible as explained in wcsbth() note 5.
*
*   ctrl      int       Error reporting and other control options for invalid
*                       WCS and other header keyrecords:
*                           0: Do not report any rejected header keyrecords.
*                           1: Produce a one-line message stating the number
*                              of WCS keyrecords rejected (nreject).
*                           2: Report each rejected keyrecord and the reason
*                              why it was rejected.
*                           3: As above, but also report all non-WCS
*                              keyrecords that were discarded, and the number
*                              of coordinate representations (nwcs) found.
*                           4: As above, but also report the accepted WCS
*                              keyrecords, with a summary of the number
*                              accepted as well as rejected.
*                       The report is written to stderr by default, or the
*                       stream set by wcsprintf_set().
*
*                       For ctrl < 0, WCS keyrecords processed by wcspih()
*                       are removed from header[]:
*                          -1: Remove only valid WCS keyrecords whose values
*                              were successfully extracted, nothing is
*                              reported.
*                          -2: As above, but also remove WCS keyrecords that
*                              were rejected, reporting each one and the
*                              reason that it was rejected.
*                          -3: As above, and also report the number of
*                              coordinate representations (nwcs) found.
*                         -11: Same as -1 but preserving global WCS-related
*                              keywords such as '{DATE,MJD}-{OBS,BEG,AVG,END}'
*                              and the other basic time-related keywords, and
*                              'OBSGEO-{X,Y,Z,L,B,H}'.
*                       If any keyrecords are removed from header[] it will
*                       be null-terminated (NUL not being a legal FITS header
*                       character), otherwise it will contain its original
*                       complement of nkeyrec keyrecords and possibly not be
*                       null-terminated.
*
* Returned:
*   nreject   int*      Number of WCS keywords rejected for syntax errors,
*                       illegal values, etc.  Keywords not recognized as WCS
*                       keywords are simply ignored.  Refer also to wcsbth()
*                       note 5.
*
*   nwcs      int*      Number of coordinate representations found.
*
*   wcs       struct wcsprm**
*                       Pointer to an array of wcsprm structs containing up to
*                       27 coordinate representations.
*
*                       Memory for the array is allocated by wcspih() which
*                       also invokes wcsini() for each struct to allocate
*                       memory for internal arrays and initialize their
*                       members to default values.  Refer also to wcsbth()
*                       note 8.  Note that wcsset() is not invoked on these
*                       structs.
*
*                       This allocated memory must be freed by the user, first
*                       by invoking wcsfree() for each struct, and then by
*                       freeing the array itself.  A routine, wcsvfree(), is
*                       provided to do this (see below).
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                         4: Fatal error returned by Flex parser.
*
* Notes:
*   1: Refer to wcsbth() notes 1, 2, 3, 5, 7, and 8.
*
*
* wcsbth() - FITS WCS parser routine for binary table and image headers
* ---------------------------------------------------------------------
* wcsbth() is a high-level FITS WCS routine that parses a binary table header.
* It handles image array and pixel list WCS keywords which may be present
* together in one header.
*
* As an extension of the FITS WCS standard, wcsbth() also recognizes image
* header keywords in a binary table header.  These may be used to provide
* default values via an inheritance mechanism discussed in note 5 (c.f.
* WCSHDR_AUXIMG and WCSHDR_ALLIMG), or may instead result in wcsprm structs
* that are not associated with any particular column.  Thus wcsbth() can
* handle primary image and image extension headers in addition to binary table
* headers (it ignores NAXIS and does not rely on the presence of the TFIELDS
* keyword).
*
* All WCS keywords defined in Papers I, II, III, and VII are recognized, and
* also those used by the AIPS convention and certain other keywords that
* existed in early drafts of the WCS papers as explained in note 5 below.
*
* wcsbth() sets the colnum or colax[] members of the wcsprm structs that it
* returns with the column number of an image array or the column numbers
* associated with each pixel coordinate element in a pixel list.  wcsprm
* structs that are not associated with any particular column, as may be
* derived from image header keywords, have colnum == 0.
*
* Note 6 below discusses the number of wcsprm structs returned by wcsbth(),
* and the circumstances in which image header keywords cause a struct to be
* created.  See also note 9 concerning the number of separate images that may
* be stored in a pixel list.
*
* The API to wcsbth() is similar to that of wcspih() except for the addition
* of extra arguments that may be used to restrict its operation.  Like
* wcspih(), wcsbth() invokes wcstab() on each of the wcsprm structs that it
* returns.
*
* Given and returned:
*   header    char[]    Character array containing the (entire) FITS binary
*                       table, primary image, or image extension header from
*                       which to identify and construct the coordinate
*                       representations, for example, as might be obtained
*                       conveniently via the CFITSIO routine fits_hdr2str().
*
*                       Each header "keyrecord" (formerly "card image")
*                       consists of exactly 80 7-bit ASCII printing
*                       characters in the range 0x20 to 0x7e (which excludes
*                       NUL, BS, TAB, LF, FF and CR) especially noting that
*                       the keyrecords are NOT null-terminated.
*
*                       For negative values of ctrl (see below), header[] is
*                       modified so that WCS keyrecords processed by wcsbth()
*                       are removed from it.
*
* Given:
*   nkeyrec   int       Number of keyrecords in header[].
*
*   relax     int       Degree of permissiveness:
*                         0: Recognize only FITS keywords defined by the
*                            published WCS standard.
*                         WCSHDR_all: Admit all recognized informal
*                            extensions of the WCS standard.
*                       Fine-grained control of the degree of permissiveness
*                       is also possible, as explained in note 5 below.
*
*   ctrl      int       Error reporting and other control options for invalid
*                       WCS and other header keyrecords:
*                           0: Do not report any rejected header keyrecords.
*                           1: Produce a one-line message stating the number
*                              of WCS keyrecords rejected (nreject).
*                           2: Report each rejected keyrecord and the reason
*                              why it was rejected.
*                           3: As above, but also report all non-WCS
*                              keyrecords that were discarded, and the number
*                              of coordinate representations (nwcs) found.
*                           4: As above, but also report the accepted WCS
*                              keyrecords, with a summary of the number
*                              accepted as well as rejected.
*                       The report is written to stderr by default, or the
*                       stream set by wcsprintf_set().
*
*                       For ctrl < 0, WCS keyrecords processed by wcsbth()
*                       are removed from header[]:
*                          -1: Remove only valid WCS keyrecords whose values
*                              were successfully extracted, nothing is
*                              reported.
*                          -2: Also remove WCS keyrecords that were rejected,
*                              reporting each one and the reason that it was
*                              rejected.
*                          -3: As above, and also report the number of
*                              coordinate representations (nwcs) found.
*                         -11: Same as -1 but preserving global WCS-related
*                              keywords such as '{DATE,MJD}-{OBS,BEG,AVG,END}'
*                              and the other basic time-related keywords, and
*                              'OBSGEO-{X,Y,Z,L,B,H}'.
*                       If any keyrecords are removed from header[] it will
*                       be null-terminated (NUL not being a legal FITS header
*                       character), otherwise it will contain its original
*                       complement of nkeyrec keyrecords and possibly not be
*                       null-terminated.
*
*   keysel    int       Vector of flag bits that may be used to restrict the
*                       keyword types considered:
*                         WCSHDR_IMGHEAD: Image header keywords.
*                         WCSHDR_BIMGARR: Binary table image array.
*                         WCSHDR_PIXLIST: Pixel list keywords.
*                       If zero, there is no restriction.
*
*                       Keywords such as EQUIna or RFRQna that are common to
*                       binary table image arrays and pixel lists (including
*                       WCSNna and TWCSna, as explained in note 4 below) are
*                       selected by both WCSHDR_BIMGARR and WCSHDR_PIXLIST.
*                       Thus if inheritance via WCSHDR_ALLIMG is enabled as
*                       discussed in note 5 and one of these shared keywords
*                       is present, then WCSHDR_IMGHEAD and WCSHDR_PIXLIST
*                       alone may be sufficient to cause the construction of
*                       coordinate descriptions for binary table image arrays.
*
*   colsel    int*      Pointer to an array of table column numbers used to
*                       restrict the keywords considered by wcsbth().
*
*                       A null pointer may be specified to indicate that there
*                       is no restriction.  Otherwise, the magnitude of
*                       cols[0] specifies the length of the array:
*                         cols[0] > 0: the columns are included,
*                         cols[0] < 0: the columns are excluded.
*
*                       For the pixel list keywords TPn_ka and TCn_ka (and
*                       TPCn_ka and TCDn_ka if WCSHDR_LONGKEY is enabled), it
*                       is an error for one column to be selected but not the
*                       other.  This is unlike the situation with invalid
*                       keyrecords, which are simply rejected, because the
*                       error is not intrinsic to the header itself but
*                       arises in the way that it is processed.
*
* Returned:
*   nreject   int*      Number of WCS keywords rejected for syntax errors,
*                       illegal values, etc.  Keywords not recognized as WCS
*                       keywords are simply ignored, refer also to note 5
*                       below.
*
*   nwcs      int*      Number of coordinate representations found.
*
*   wcs       struct wcsprm**
*                       Pointer to an array of wcsprm structs containing up
*                       to 27027 coordinate representations, refer to note 6
*                       below.
*
*                       Memory for the array is allocated by wcsbth() which
*                       also invokes wcsini() for each struct to allocate
*                       memory for internal arrays and initialize their
*                       members to default values.  Refer also to note 8
*                       below.  Note that wcsset() is not invoked on these
*                       structs.
*
*                       This allocated memory must be freed by the user, first
*                       by invoking wcsfree() for each struct, and then by
*                       freeing the array itself.  A routine, wcsvfree(), is
*                       provided to do this (see below).
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                         3: Invalid column selection.
*                         4: Fatal error returned by Flex parser.
*
* Notes:
*   1: wcspih() determines the number of coordinate axes independently for
*      each alternate coordinate representation (denoted by the "a" value in
*      keywords like CTYPEia) from the higher of
*
*        a: NAXIS,
*        b: WCSAXESa,
*        c: The highest axis number in any parameterized WCS keyword.  The
*           keyvalue, as well as the keyword, must be syntactically valid
*           otherwise it will not be considered.
*
*      If none of these keyword types is present, i.e. if the header only
*      contains auxiliary WCS keywords for a particular coordinate
*      representation, then no coordinate description is constructed for it.
*
*      wcsbth() is similar except that it ignores the NAXIS keyword if given
*      an image header to process.
*
*      The number of axes, which is returned as a member of the wcsprm
*      struct, may differ for different coordinate representations of the
*      same image.
*
*   2: wcspih() and wcsbth() enforce correct FITS "keyword = value" syntax
*      with regard to "= " occurring in columns 9 and 10.
*
*      However, they do recognize free-format character (NOST 100-2.0,
*      Sect. 5.2.1), integer (Sect. 5.2.3), and floating-point values
*      (Sect. 5.2.4) for all keywords.
*
*   3: Where CROTAn, CDi_ja, and PCi_ja occur together in one header wcspih()
*      and wcsbth() treat them as described in the prologue to wcs.h.
*
*   4: WCS Paper I mistakenly defined the pixel list form of WCSNAMEa as
*      TWCSna instead of WCSNna; the 'T' is meant to substitute for the axis
*      number in the binary table form of the keyword - note that keywords
*      defined in WCS Papers II, III, and VII that are not parameterized by
*      axis number have identical forms for binary tables and pixel lists.
*      Consequently wcsbth() always treats WCSNna and TWCSna as equivalent.
*
*   5: wcspih() and wcsbth() interpret the "relax" argument as a vector of
*      flag bits to provide fine-grained control over what non-standard WCS
*      keywords to accept.  The flag bits are subject to change in future and
*      should be set by using the preprocessor macros (see below) for the
*      purpose.
*
*      - WCSHDR_none: Don't accept any extensions (not even those in the
*              errata).  Treat non-conformant keywords in the same way as
*              non-WCS keywords in the header, i.e. simply ignore them.
*
*      - WCSHDR_all: Accept all extensions recognized by the parser.
*
*      - WCSHDR_reject: Reject non-standard keyrecords (that are not otherwise
*              explicitly accepted by one of the flags below).  A message will
*              optionally be printed on stderr by default, or the stream set
*              by wcsprintf_set(), as determined by the ctrl argument, and
*              nreject will be incremented.
*
*              This flag may be used to signal the presence of non-standard
*              keywords, otherwise they are simply passed over as though they
*              did not exist in the header.  It is mainly intended for testing
*              conformance of a FITS header to the WCS standard.
*
*              Keyrecords may be non-standard in several ways:
*
*                - The keyword may be syntactically valid but with keyvalue of
*                  incorrect type or invalid syntax, or the keycomment may be
*                  malformed.
*
*                - The keyword may strongly resemble a WCS keyword but not, in
*                  fact, be one because it does not conform to the standard.
*                  For example, "CRPIX01" looks like a CRPIXja keyword, but in
*                  fact the leading zero on the axis number violates the basic
*                  FITS standard.  Likewise, "LONPOLE2" is not a valid
*                  LONPOLEa keyword in the WCS standard, and indeed there is
*                  nothing the parser can sensibly do with it.
*
*                - Use of the keyword may be deprecated by the standard.  Such
*                  will be rejected if not explicitly accepted via one of the
*                  flags below.
*
*      - WCSHDR_strict: As for WCSHDR_reject, but also reject AIPS-convention
*              keywords and all other deprecated usage that is not explicitly
*              accepted.
*
*      - WCSHDR_CROTAia: Accept CROTAia (wcspih()),
*                               iCROTna (wcsbth()),
*                               TCROTna (wcsbth()).
*      - WCSHDR_VELREFa: Accept VELREFa.
*              wcspih() always recognizes the AIPS-convention keywords,
*              CROTAn, EPOCH, and VELREF for the primary representation
*              (a = ' ') but alternates are non-standard.
*
*              wcsbth() accepts EPOCHa and VELREFa only if WCSHDR_AUXIMG is
*              also enabled.
*
*      - WCSHDR_CD00i00j: Accept CD00i00j (wcspih()).
*      - WCSHDR_PC00i00j: Accept PC00i00j (wcspih()).
*      - WCSHDR_PROJPn:   Accept PROJPn   (wcspih()).
*              These appeared in early drafts of WCS Paper I+II (before they
*              were split) and are equivalent to CDi_ja, PCi_ja, and PVi_ma
*              for the primary representation (a = ' ').  PROJPn is
*              equivalent to PVi_ma with m = n <= 9, and is associated
*              exclusively with the latitude axis.
*
*      - WCSHDR_CD0i_0ja: Accept CD0i_0ja (wcspih()).
*      - WCSHDR_PC0i_0ja: Accept PC0i_0ja (wcspih()).
*      - WCSHDR_PV0i_0ma: Accept PV0i_0ja (wcspih()).
*      - WCSHDR_PS0i_0ma: Accept PS0i_0ja (wcspih()).
*              Allow the numerical index to have a leading zero in doubly-
*              parameterized keywords, for example, PC01_01.  WCS Paper I
*              (Sects 2.1.2 & 2.1.4) explicitly disallows leading zeroes.
*              The FITS 3.0 standard document (Sect. 4.1.2.1) states that the
*              index in singly-parameterized keywords (e.g. CTYPEia) "shall
*              not have leading zeroes", and later in Sect. 8.1 that "leading
*              zeroes must not be used" on PVi_ma and PSi_ma.  However, by an
*              oversight, it is silent on PCi_ja and CDi_ja.
*
*      - WCSHDR_DOBSn (wcsbth() only): Allow DOBSn, the column-specific
*              analogue of DATE-OBS.  By an oversight this was never formally
*              defined in the standard.
*
*      - WCSHDR_OBSGLBHn (wcsbth() only): Allow OBSGLn, OBSGBn, and OBSGHn,
*              the column-specific analogues of OBSGEO-L, OBSGEO-B, and
*              OBSGEO-H.  By an oversight these were never formally defined in
*              the standard.
*
*      - WCSHDR_RADECSYS: Accept RADECSYS.  This appeared in early drafts of
*              WCS Paper I+II and was subsequently replaced by RADESYSa.
*
*              wcsbth() accepts RADECSYS only if WCSHDR_AUXIMG is also
*              enabled.
*
*      - WCSHDR_EPOCHa:  Accept EPOCHa.
*
*      - WCSHDR_VSOURCE: Accept VSOURCEa or VSOUna (wcsbth()).  This appeared
*              in early drafts of WCS Paper III and was subsequently dropped
*              in favour of ZSOURCEa and ZSOUna.
*
*              wcsbth() accepts VSOURCEa only if WCSHDR_AUXIMG is also
*              enabled.
*
*      - WCSHDR_DATEREF: Accept DATE-REF, MJD-REF, MJD-REFI, MJD-REFF, JDREF,
*              JD-REFI, and JD-REFF as synonyms for the standard keywords,
*              DATEREF, MJDREF, MJDREFI, MJDREFF, JDREF, JDREFI, and JDREFF.
*              The latter buck the pattern set by the other date keywords
*              ({DATE,MJD}-{OBS,BEG,AVG,END}), thereby increasing the
*              potential for confusion and error.
*
*      - WCSHDR_LONGKEY (wcsbth() only): Accept long forms of the alternate
*              binary table and pixel list WCS keywords, i.e. with "a" non-
*              blank.  Specifically
*
#                jCRPXna  TCRPXna  :  jCRPXn  jCRPna  TCRPXn  TCRPna  CRPIXja
#                   -     TPCn_ka  :    -     ijPCna    -     TPn_ka  PCi_ja
#                   -     TCDn_ka  :    -     ijCDna    -     TCn_ka  CDi_ja
#                iCDLTna  TCDLTna  :  iCDLTn  iCDEna  TCDLTn  TCDEna  CDELTia
#                iCUNIna  TCUNIna  :  iCUNIn  iCUNna  TCUNIn  TCUNna  CUNITia
#                iCTYPna  TCTYPna  :  iCTYPn  iCTYna  TCTYPn  TCTYna  CTYPEia
#                iCRVLna  TCRVLna  :  iCRVLn  iCRVna  TCRVLn  TCRVna  CRVALia
#                iPVn_ma  TPVn_ma  :    -     iVn_ma    -     TVn_ma  PVi_ma
#                iPSn_ma  TPSn_ma  :    -     iSn_ma    -     TSn_ma  PSi_ma
*
*              where the primary and standard alternate forms together with
*              the image-header equivalent are shown rightwards of the colon.
*
*              The long form of these keywords could be described as quasi-
*              standard.  TPCn_ka, iPVn_ma, and TPVn_ma appeared by mistake
*              in the examples in WCS Paper II and subsequently these and
*              also TCDn_ka, iPSn_ma and TPSn_ma were legitimized by the
*              errata to the WCS papers.
*
*              Strictly speaking, the other long forms are non-standard and
*              in fact have never appeared in any draft of the WCS papers nor
*              in the errata.  However, as natural extensions of the primary
*              form they are unlikely to be written with any other intention.
*              Thus it should be safe to accept them provided, of course,
*              that the resulting keyword does not exceed the 8-character
*              limit.
*
*              If WCSHDR_CNAMn is enabled then also accept
*
#                iCNAMna  TCNAMna  :   ---   iCNAna    ---   TCNAna  CNAMEia
#                iCRDEna  TCRDEna  :   ---   iCRDna    ---   TCRDna  CRDERia
#                iCSYEna  TCSYEna  :   ---   iCSYna    ---   TCSYna  CSYERia
#                iCZPHna  TCZPHna  :   ---   iCZPna    ---   TCZPna  CZPHSia
#                iCPERna  TCPERna  :   ---   iCPRna    ---   TCPRna  CPERIia
*
*              Note that CNAMEia, CRDERia, CSYERia, CZPHSia, CPERIia, and
*              their variants are not used by WCSLIB but are stored in the
*              wcsprm struct as auxiliary information.
*
*      - WCSHDR_CNAMn (wcsbth() only): Accept iCNAMn, iCRDEn, iCSYEn, iCZPHn,
*              iCPERn, TCNAMn, TCRDEn, TCSYEn, TCZPHn, and TCPERn, i.e. with
*              "a" blank.  While non-standard, these are the obvious analogues
*              of iCTYPn, TCTYPn, etc.
*
*      - WCSHDR_AUXIMG (wcsbth() only): Allow the image-header form of an
*              auxiliary WCS keyword with representation-wide scope to
*              provide a default value for all images.  This default may be
*              overridden by the column-specific form of the keyword.
*
*              For example, a keyword like EQUINOXa would apply to all image
*              arrays in a binary table, or all pixel list columns with
*              alternate representation "a" unless overridden by EQUIna.
*
*              Specifically the keywords are:
*
#                LONPOLEa  for LONPna
#                LATPOLEa  for LATPna
#                VELREF        -       ... (No column-specific form.)
#                VELREFa       -       ... Only if WCSHDR_VELREFa is set.
*
*              whose keyvalues are actually used by WCSLIB, and also keywords
*              providing auxiliary information that is simply stored in the
*              wcsprm struct:
*
#                WCSNAMEa  for WCSNna  ... Or TWCSna (see below).
#
#                DATE-OBS  for DOBSn
#                MJD-OBS   for MJDOBn
#
#                RADESYSa  for RADEna
#                RADECSYS  for RADEna  ... Only if WCSHDR_RADECSYS is set.
#                EPOCH         -       ... (No column-specific form.)
#                EPOCHa        -       ... Only if WCSHDR_EPOCHa is set.
#                EQUINOXa  for EQUIna
*
*              where the image-header keywords on the left provide default
*              values for the column specific keywords on the right.
*
*              Note that, according to Sect. 8.1 of WCS Paper III, and
*              Sect. 5.2 of WCS Paper VII, the following are always inherited:
*
#                RESTFREQ  for RFRQna
#                RESTFRQa  for RFRQna
#                RESTWAVa  for RWAVna
*
*              being those actually used by WCSLIB, together with the
*              following auxiliary keywords, many of which do not have binary
*              table equivalents and therefore can only be inherited:
*
#                TIMESYS       -
#                TREFPOS   for TRPOSn
#                TREFDIR   for TRDIRn
#                PLEPHEM       -
#                TIMEUNIT      -
#                DATEREF       -
#                MJDREF        -
#                MJDREFI       -
#                MJDREFF       -
#                JDREF         -
#                JDREFI        -
#                JDREFF        -
#                TIMEOFFS      -
#
#                DATE-BEG      -
#                DATE-AVG  for DAVGn
#                DATE-END      -
#                MJD-BEG       -
#                MJD-AVG   for MJDAn
#                MJD-END       -
#                JEPOCH        -
#                BEPOCH        -
#                TSTART        -
#                TSTOP         -
#                XPOSURE       -
#                TELAPSE       -
#
#                TIMSYER       -
#                TIMRDER       -
#                TIMEDEL       -
#                TIMEPIXR      -
#
#                OBSGEO-X  for OBSGXn
#                OBSGEO-Y  for OBSGYn
#                OBSGEO-Z  for OBSGZn
#                OBSGEO-L  for OBSGLn
#                OBSGEO-B  for OBSGBn
#                OBSGEO-H  for OBSGHn
#                OBSORBIT      -
#
#                SPECSYSa  for SPECna
#                SSYSOBSa  for SOBSna
#                VELOSYSa  for VSYSna
#                VSOURCEa  for VSOUna  ... Only if WCSHDR_VSOURCE is set.
#                ZSOURCEa  for ZSOUna
#                SSYSSRCa  for SSRCna
#                VELANGLa  for VANGna
*
*              Global image-header keywords, such as MJD-OBS, apply to all
*              alternate representations, and would therefore provide a
*              default value for all images in the header.
*
*              This auxiliary inheritance mechanism applies to binary table
*              image arrays and pixel lists alike.  Most of these keywords
*              have no default value, the exceptions being LONPOLEa and
*              LATPOLEa, and also RADESYSa and EQUINOXa which provide
*              defaults for each other.  Thus one potential difficulty in
*              using WCSHDR_AUXIMG is that of erroneously inheriting one of
*              these four keywords.
*
*              Also, beware of potential inconsistencies that may arise where,
*              for example, DATE-OBS is inherited, but MJD-OBS is overridden
*              by MJDOBn and specifies a different time.  Pairs in this
*              category are:
*
=                    DATE-OBS/DOBSn       versus       MJD-OBS/MJDOBn
=                    DATE-AVG/DAVGn       versus       MJD-AVG/MJDAn
=                    RESTFRQa/RFRQna      versus      RESTWAVa/RWAVna
=                OBSGEO-[XYZ]/OBSG[XYZ]n  versus  OBSGEO-[LBH]/OBSG[LBH]n
*
*              The wcsfixi() routines datfix() and obsfix() are provided to
*              check the consistency of these and other such pairs of
*              keywords.
*
*              Unlike WCSHDR_ALLIMG, the existence of one (or all) of these
*              auxiliary WCS image header keywords will not by itself cause a
*              wcsprm struct to be created for alternate representation "a".
*              This is because they do not provide sufficient information to
*              create a non-trivial coordinate representation when used in
*              conjunction with the default values of those keywords that are
*              parameterized by axis number, such as CTYPEia.
*
*      - WCSHDR_ALLIMG (wcsbth() only): Allow the image-header form of *all*
*              image header WCS keywords to provide a default value for all
*              image arrays in a binary table (n.b. not pixel list).  This
*              default may be overridden by the column-specific form of the
*              keyword.
*
*              For example, a keyword like CRPIXja would apply to all image
*              arrays in a binary table with alternate representation "a"
*              unless overridden by jCRPna.
*
*              Specifically the keywords are those listed above for
*              WCSHDR_AUXIMG plus
*
#                WCSAXESa  for WCAXna
*
*              which defines the coordinate dimensionality, and the following
*              keywords that are parameterized by axis number:
*
#                CRPIXja   for jCRPna
#                PCi_ja    for ijPCna
#                CDi_ja    for ijCDna
#                CDELTia   for iCDEna
#                CROTAi    for iCROTn
#                CROTAia        -      ... Only if WCSHDR_CROTAia is set.
#                CUNITia   for iCUNna
#                CTYPEia   for iCTYna
#                CRVALia   for iCRVna
#                PVi_ma    for iVn_ma
#                PSi_ma    for iSn_ma
#
#                CNAMEia   for iCNAna
#                CRDERia   for iCRDna
#                CSYERia   for iCSYna
#                CZPHSia   for iCZPna
#                CPERIia   for iCPRna
*
*              where the image-header keywords on the left provide default
*              values for the column specific keywords on the right.
*
*              This full inheritance mechanism only applies to binary table
*              image arrays, not pixel lists, because in the latter case
*              there is no well-defined association between coordinate axis
*              number and column number (see note 9 below).
*
*              Note that CNAMEia, CRDERia, CSYERia, and their variants are
*              not used by WCSLIB but are stored in the wcsprm struct as
*              auxiliary information.
*
*              Note especially that at least one wcsprm struct will be
*              returned for each "a" found in one of the image header
*              keywords listed above:
*
*              - If the image header keywords for "a" ARE NOT inherited by a
*                binary table, then the struct will not be associated with
*                any particular table column number and it is up to the user
*                to provide an association.
*
*              - If the image header keywords for "a" ARE inherited by a
*                binary table image array, then those keywords are considered
*                to be "exhausted" and do not result in a separate wcsprm
*                struct.
*
*      For example, to accept CD00i00j and PC00i00j and reject all other
*      extensions, use
*
=        relax = WCSHDR_reject | WCSHDR_CD00i00j | WCSHDR_PC00i00j;
*
*      The parser always treats EPOCH as subordinate to EQUINOXa if both are
*      present, and VSOURCEa is always subordinate to ZSOURCEa.
*
*      Likewise, VELREF is subordinate to the formalism of WCS Paper III, see
*      spcaips().
*
*      Neither wcspih() nor wcsbth() currently recognize the AIPS-convention
*      keywords ALTRPIX or ALTRVAL which effectively define an alternative
*      representation for a spectral axis.
*
*   6: Depending on what flags have been set in its "relax" argument,
*      wcsbth() could return as many as 27027 wcsprm structs:
*
*      - Up to 27 unattached representations derived from image header
*        keywords.
*
*      - Up to 27 structs for each of up to 999 columns containing an image
*        arrays.
*
*      - Up to 27 structs for a pixel list.
*
*      Note that it is considered legitimate for a column to contain an image
*      array and also form part of a pixel list, and in particular that
*      wcsbth() does not check the TFORM keyword for a pixel list column to
*      check that it is scalar.
*
*      In practice, of course, a realistic binary table header is unlikely to
*      contain more than a handful of images.
*
*      In order for wcsbth() to create a wcsprm struct for a particular
*      coordinate representation, at least one WCS keyword that defines an
*      axis number must be present, either directly or by inheritance if
*      WCSHDR_ALLIMG is set.
*
*      When the image header keywords for an alternate representation are
*      inherited by a binary table image array via WCSHDR_ALLIMG, those
*      keywords are considered to be "exhausted" and do not result in a
*      separate wcsprm struct.  Otherwise they do.
*
*   7: Neither wcspih() nor wcsbth() check for duplicated keywords, in most
*      cases they accept the last encountered.
*
*   8: wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue
*      of wcs.h) to match the size of the pv[] and ps[] arrays in the wcsprm
*      structs to the number in the header.  Consequently there are no unused
*      elements in the pv[] and ps[] arrays, indeed they will often be of
*      zero length.
*
*   9: The FITS WCS standard for pixel lists assumes that a pixel list
*      defines one and only one image, i.e. that each row of the binary table
*      refers to just one event, e.g. the detection of a single photon or
*      neutrino, for which the device "pixel" coordinates are stored in
*      separate scalar columns of the table.
*
*      In the absence of a standard for pixel lists - or even an informal
*      description! - let alone a formal mechanism for identifying the columns
*      containing pixel coordinates (as opposed to pixel values or metadata
*      recorded at the time the photon or neutrino was detected), WCS Paper I
*      discusses how the WCS keywords themselves may be used to identify them.
*
*      In practice, however, pixel lists have been used to store multiple
*      images.  Besides not specifying how to identify columns, the pixel list
*      convention is also silent on the method to be used to associate table
*      columns with image axes.
*
*      An additional shortcoming is the absence of a formal method for
*      associating global binary-table WCS keywords, such as WCSNna or MJDOBn,
*      with a pixel list image, whether one or several.
*
*      In light of these uncertainties, wcsbth() simply collects all WCS
*      keywords for a particular pixel list coordinate representation (i.e.
*      the "a" value in TCTYna) into one wcsprm struct.  However, these
*      alternates need not be associated with the same table columns and this
*      allows a pixel list to contain up to 27 separate images.  As usual, if
*      one of these representations happened to contain more than two
*      celestial axes, for example, then an error would result when wcsset()
*      is invoked on it.  In this case the "colsel" argument could be used to
*      restrict the columns used to construct the representation so that it
*      only contained one pair of celestial axes.
*
*      Global, binary-table WCS keywords are considered to apply to the pixel
*      list image with matching alternate (e.g. the "a" value in LONPna or
*      EQUIna), regardless of the table columns the image occupies.  In other
*      words, the column number is ignored (the "n" value in LONPna or
*      EQUIna).  This also applies for global, binary-table WCS keywords that
*      have no alternates, such as MJDOBn and OBSGXn, which match all images
*      in a pixel list.  Take heed that this may lead to counterintuitive
*      behaviour, especially where such a keyword references a column that
*      does not store pixel coordinates, and moreso where the pixel list
*      stores only a single image.  In fact, as the column number, n, is
*      ignored for such keywords, it would make no difference even if they
*      referenced non-existent columns.  Moreover, there is no requirement for
*      consistency in the column numbers used for such keywords, even for
*      OBSGXn, OBSGYn, and OBSGZn which are meant to define the elements of a
*      coordinate vector.  Although it would surely be perverse to construct a
*      pixel list like this, such a situation may still arise in practice
*      where columns are deleted from a binary table.
*
*      The situation with global, binary-table WCS keywords becomes
*      potentially even more confusing when image arrays and pixel list images
*      coexist in one binary table.  In that case, a keyword such as MJDOBn
*      may legitimately appear multiple times with n referencing different
*      image arrays.  Which then is the one that applies to the pixel list
*      images?  In this implementation, it is the last instance that appears
*      in the header, whether or not it is also associated with an image
*      array.
*
*
* wcstab() - Tabular construction routine
* ---------------------------------------
* wcstab() assists in filling in the information in the wcsprm struct relating
* to coordinate lookup tables.
*
* Tabular coordinates ('TAB') present certain difficulties in that the main
* components of the lookup table - the multidimensional coordinate array plus
* an index vector for each dimension - are stored in a FITS binary table
* extension (BINTABLE).  Information required to locate these arrays is stored
* in PVi_ma and PSi_ma keywords in the image header.
*
* wcstab() parses the PVi_ma and PSi_ma keywords associated with each 'TAB'
* axis and allocates memory in the wcsprm struct for the required number of
* tabprm structs.  It sets as much of the tabprm struct as can be gleaned from
* the image header, and also sets up an array of wtbarr structs (described in
* the prologue of wtbarr.h) to assist in extracting the required arrays from
* the BINTABLE extension(s).
*
* It is then up to the user to allocate memory for, and copy arrays from the
* BINTABLE extension(s) into the tabprm structs.  A CFITSIO routine,
* fits_read_wcstab(), has been provided for this purpose, see getwcstab.h.
* wcsset() will automatically take control of this allocated memory, in
* particular causing it to be freed by wcsfree(); the user must not attempt
* to free it after wcsset() has been called.
*
* Note that wcspih() and wcsbth() automatically invoke wcstab() on each of the
* wcsprm structs that they return.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters (see below).
*
*                       wcstab() sets ntab, tab, nwtb and wtb, allocating
*                       memory for the tab and wtb arrays.  This allocated
*                       memory will be freed automatically by wcsfree().
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                         3: Invalid tabular parameters.
*
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err if enabled, see wcserr_enable().
*
*
* wcsidx() - Index alternate coordinate representations
* -----------------------------------------------------
* wcsidx() returns an array of 27 indices for the alternate coordinate
* representations in the array of wcsprm structs returned by wcspih().  For
* the array returned by wcsbth() it returns indices for the unattached
* (colnum == 0) representations derived from image header keywords - use
* wcsbdx() for those derived from binary table image arrays or pixel lists
* keywords.
*
* Given:
*   nwcs      int       Number of coordinate representations in the array.
*
*   wcs       const struct wcsprm**
*                       Pointer to an array of wcsprm structs returned by
*                       wcspih() or wcsbth().
*
* Returned:
*   alts      int[27]   Index of each alternate coordinate representation in
*                       the array: alts[0] for the primary, alts[1] for 'A',
*                       etc., set to -1 if not present.
*
*                       For example, if there was no 'P' representation then
*
=                         alts['P'-'A'+1] == -1;
*
*                       Otherwise, the address of its wcsprm struct would be
*
=                         wcs + alts['P'-'A'+1];
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsbdx() - Index alternate coordinate representions
* ---------------------------------------------------
* wcsbdx() returns an array of 999 x 27 indices for the alternate coordinate
* representions for binary table image arrays xor pixel lists in the array of
* wcsprm structs returned by wcsbth().  Use wcsidx() for the unattached
* representations derived from image header keywords.
*
* Given:
*   nwcs      int       Number of coordinate representations in the array.
*
*   wcs       const struct wcsprm**
*                       Pointer to an array of wcsprm structs returned by
*                       wcsbth().
*
*   type      int       Select the type of coordinate representation:
*                         0: binary table image arrays,
*                         1: pixel lists.
*
* Returned:
*   alts      short[1000][28]
*                       Index of each alternate coordinate represention in the
*                       array: alts[col][0] for the primary, alts[col][1] for
*                       'A', to alts[col][26] for 'Z', where col is the
*                       1-relative column number, and col == 0 is used for
*                       unattached image headers.  Set to -1 if not present.
*
*                       alts[col][27] counts the number of coordinate
*                       representations of the chosen type for each column.
*
*                       For example, if there was no 'P' represention for
*                       column 13 then
*
=                         alts[13]['P'-'A'+1] == -1;
*
*                       Otherwise, the address of its wcsprm struct would be
*
=                         wcs + alts[13]['P'-'A'+1];
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsvfree() - Free the array of wcsprm structs
* ---------------------------------------------
* wcsvfree() frees the memory allocated by wcspih() or wcsbth() for the array
* of wcsprm structs, first invoking wcsfree() on each of the array members.
*
* Given and returned:
*   nwcs      int*      Number of coordinate representations found; set to 0
*                       on return.
*
*   wcs       struct wcsprm**
*                       Pointer to the array of wcsprm structs; set to 0x0 on
*                       return.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcshdo() - Write out a wcsprm struct as a FITS header
* -----------------------------------------------------
* wcshdo() translates a wcsprm struct into a FITS header.  If the colnum
* member of the struct is non-zero then a binary table image array header will
* be produced.  Otherwise, if the colax[] member of the struct is set non-zero
* then a pixel list header will be produced.  Otherwise, a primary image or
* image extension header will be produced.
*
* If the struct was originally constructed from a header, e.g. by wcspih(),
* the output header will almost certainly differ in a number of respects:
*
*   - The output header only contains WCS-related keywords.  In particular, it
*     does not contain syntactically-required keywords such as SIMPLE, NAXIS,
*     BITPIX, or END.
*
*   - Elements of the PCi_ja matrix will be written if and only if they differ
*     from the unit matrix.  Thus, if the matrix is unity then no elements
*     will be written.
*
*   - The redundant keywords MJDREF, JDREF, JDREFI, JDREFF, all of which
*     duplicate MJDREFI + MJDREFF, are never written.  OBSGEO-[LBH] are not
*     written if OBSGEO-[XYZ] are defined.
*
*   - Deprecated (e.g. CROTAn, RESTFREQ, VELREF, RADECSYS, EPOCH, VSOURCEa) or
*     non-standard usage will be translated to standard (this is partially
*     dependent on whether wcsfix() was applied).
*
*   - Additional keywords such as WCSAXESa, CUNITia, LONPOLEa and LATPOLEa may
*     appear.
*
*   - Quantities will be converted to the units used internally, basically SI
*     with the addition of degrees.
*
*   - Floating-point quantities may be given to a different decimal precision.
*
*   - The original keycomments will be lost, although wcshdo() tries hard to
*     write meaningful comments.
*
*   - Keyword order will almost certainly be changed.
*
* Keywords can be translated between the image array, binary table, and pixel
* lists forms by manipulating the colnum or colax[] members of the wcsprm
* struct.
*
* Given:
*   ctrl      int       Vector of flag bits that controls the degree of
*                       permissiveness in departing from the published WCS
*                       standard, and also controls the formatting of
*                       floating-point keyvalues.  Set it to zero to get the
*                       default behaviour.
*
*                       Flag bits for the degree of permissiveness:
*                         WCSHDO_none: Recognize only FITS keywords defined by
*                            the published WCS standard.
*                         WCSHDO_all: Admit all recognized informal extensions
*                            of the WCS standard.
*                       Fine-grained control of the degree of permissiveness
*                       is also possible as explained in the notes below.
*
*                       As for controlling floating-point formatting, by
*                       default wcshdo() uses "%20.12G" for non-parameterized
*                       keywords such as LONPOLEa, and attempts to make the
*                       header more human-readable by using the same "%f"
*                       format for all values of each of the following
*                       parameterized keywords: CRPIXja, PCi_ja, and CDELTia
*                       (n.b. excluding CRVALia).  Each has the same field
*                       width and precision so that the decimal points line
*                       up.  The precision, allowing for up to 15 significant
*                       digits, is chosen so that there are no excess trailing
*                       zeroes.  A similar formatting scheme applies by
*                       default for distortion function parameters.
*
*                       However, where the values of, for example, CDELTia
*                       differ by many orders of magnitude, the default
*                       formatting scheme may cause unacceptable loss of
*                       precision for the lower-valued keyvalues.  Thus the
*                       default behaviour may be overridden:
*                         WCSHDO_P12: Use "%20.12G" format for all floating-
*                            point keyvalues (12 significant digits).
*                         WCSHDO_P13: Use "%21.13G" format for all floating-
*                            point keyvalues (13 significant digits).
*                         WCSHDO_P14: Use "%22.14G" format for all floating-
*                            point keyvalues (14 significant digits).
*                         WCSHDO_P15: Use "%23.15G" format for all floating-
*                            point keyvalues (15 significant digits).
*                         WCSHDO_P16: Use "%24.16G" format for all floating-
*                            point keyvalues (16 significant digits).
*                         WCSHDO_P17: Use "%25.17G" format for all floating-
*                            point keyvalues (17 significant digits).
*                       If more than one of the above flags are set, the
*                       highest number of significant digits prevails.  In
*                       addition, there is an anciliary flag:
*                         WCSHDO_EFMT: Use "%E" format instead of the default
*                            "%G" format above.
*                       Note that excess trailing zeroes are stripped off the
*                       fractional part with "%G" (which never occurs with
*                       "%E").  Note also that the higher-precision options
*                       eat into the keycomment area.  In this regard,
*                       WCSHDO_P14 causes minimal disruption with "%G" format,
*                       while WCSHDO_P13 is appropriate with "%E".
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Pointer to a wcsprm struct containing coordinate
*                       transformation parameters.  Will be initialized if
*                       necessary.
*
* Returned:
*   nkeyrec   int*      Number of FITS header keyrecords returned in the
*                       "header" array.
*
*   header    char**    Pointer to an array of char holding the header.
*                       Storage for the array is allocated by wcshdo() in
*                       blocks of 2880 bytes (32 x 80-character keyrecords)
*                       and must be freed by the user to avoid memory leaks.
*                       See wcsdealloc().
*
*                       Each keyrecord is 80 characters long and is *NOT*
*                       null-terminated, so the first keyrecord starts at
*                       (*header)[0], the second at (*header)[80], etc.
*
* Function return value:
*             int       Status return value (associated with wcs_errmsg[]):
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                         3: Linear transformation matrix is singular.
*                         4: Inconsistent or unrecognized coordinate axis
*                            types.
*                         5: Invalid parameter value.
*                         6: Invalid coordinate transformation parameters.
*                         7: Ill-conditioned coordinate transformation
*                            parameters.
*
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err if enabled, see wcserr_enable().
*
* Notes:
*   1: wcshdo() interprets the "relax" argument as a vector of flag bits to
*      provide fine-grained control over what non-standard WCS keywords to
*      write.  The flag bits are subject to change in future and should be set
*      by using the preprocessor macros (see below) for the purpose.
*
*      - WCSHDO_none: Don't use any extensions.
*
*      - WCSHDO_all: Write all recognized extensions, equivalent to setting
*              each flag bit.
*
*      - WCSHDO_safe: Write all extensions that are considered to be safe and
*              recommended.
*
*      - WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS
*              for use in binary tables and pixel lists.  WCS Paper III
*              introduced DATE-AVG and DAVGn but by an oversight DOBSn (the
*              obvious analogy) was never formally defined by the standard.
*              The alternative to using DOBSn is to write DATE-OBS which
*              applies to the whole table.  This usage is considered to be
*              safe and is recommended.
*
*      - WCSHDO_TPCn_ka: WCS Paper I defined
*
*              - TPn_ka and TCn_ka for pixel lists
*
*              but WCS Paper II uses TPCn_ka in one example and subsequently
*              the errata for the WCS papers legitimized the use of
*
*              - TPCn_ka and TCDn_ka for pixel lists
*
*              provided that the keyword does not exceed eight characters.
*              This usage is considered to be safe and is recommended because
*              of the non-mnemonic terseness of the shorter forms.
*
*      - WCSHDO_PVn_ma: WCS Paper I defined
*
*              - iVn_ma and iSn_ma for bintables and
*              - TVn_ma and TSn_ma for pixel lists
*
*              but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and
*              subsequently the errata for the WCS papers legitimized the use
*              of
*
*              - iPVn_ma and iPSn_ma for bintables and
*              - TPVn_ma and TPSn_ma for pixel lists
*
*              provided that the keyword does not exceed eight characters.
*              This usage is considered to be safe and is recommended because
*              of the non-mnemonic terseness of the shorter forms.
*
*      - WCSHDO_CRPXna: For historical reasons WCS Paper I defined
*
*              - jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn for bintables and
*              - TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists
*
*              for use without an alternate version specifier.  However,
*              because of the eight-character keyword constraint, in order to
*              accommodate column numbers greater than 99 WCS Paper I also
*              defined
*
*              - jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and
*              - TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists
*
*              for use with an alternate version specifier (the "a").  Like
*              the PC, CD, PV, and PS keywords there is an obvious tendency to
*              confuse these two forms for column numbers up to 99.  It is
*              very unlikely that any parser would reject keywords in the
*              first set with a non-blank alternate version specifier so this
*              usage is considered to be safe and is recommended.
*
*      - WCSHDO_CNAMna: WCS Papers I and III defined
*
*              - iCNAna,  iCRDna,  and iCSYna  for bintables and
*              - TCNAna,  TCRDna,  and TCSYna  for pixel lists
*
*              By analogy with the above, the long forms would be
*
*              - iCNAMna, iCRDEna, and iCSYEna for bintables and
*              - TCNAMna, TCRDEna, and TCSYEna for pixel lists
*
*              Note that these keywords provide auxiliary information only,
*              none of them are needed to compute world coordinates.  This
*              usage is potentially unsafe and is not recommended at this
*              time.
*
*      - WCSHDO_WCSNna: In light of wcsbth() note 4, write WCSNna instead of
*              TWCSna for pixel lists.  While wcsbth() treats WCSNna and
*              TWCSna as equivalent, other parsers may not.  Consequently,
*              this usage is potentially unsafe and is not recommended at this
*              time.
*
*
* Global variable: const char *wcshdr_errmsg[] - Status return messages
* ---------------------------------------------------------------------
* Error messages to match the status value returned from each function.
* Use wcs_errmsg[] for status returns from wcshdo().
*
*===========================================================================*/

#ifndef WCSLIB_WCSHDR
#define WCSLIB_WCSHDR

#include "wcs.h"

#ifdef __cplusplus
extern "C" {
#endif

#define WCSHDR_none     0x00000000
#define WCSHDR_all      0x000FFFFF
#define WCSHDR_reject   0x10000000
#define WCSHDR_strict   0x20000000

#define WCSHDR_CROTAia  0x00000001
#define WCSHDR_VELREFa  0x00000002
#define WCSHDR_CD00i00j 0x00000004
#define WCSHDR_PC00i00j 0x00000008
#define WCSHDR_PROJPn   0x00000010
#define WCSHDR_CD0i_0ja 0x00000020
#define WCSHDR_PC0i_0ja 0x00000040
#define WCSHDR_PV0i_0ma 0x00000080
#define WCSHDR_PS0i_0ma 0x00000100
#define WCSHDR_DOBSn    0x00000200
#define WCSHDR_OBSGLBHn 0x00000400
#define WCSHDR_RADECSYS 0x00000800
#define WCSHDR_EPOCHa   0x00001000
#define WCSHDR_VSOURCE  0x00002000
#define WCSHDR_DATEREF  0x00004000
#define WCSHDR_LONGKEY  0x00008000
#define WCSHDR_CNAMn    0x00010000
#define WCSHDR_AUXIMG   0x00020000
#define WCSHDR_ALLIMG   0x00040000

#define WCSHDR_IMGHEAD  0x00100000
#define WCSHDR_BIMGARR  0x00200000
#define WCSHDR_PIXLIST  0x00400000

#define WCSHDO_none     0x00000
#define WCSHDO_all      0x000FF
#define WCSHDO_safe     0x0000F
#define WCSHDO_DOBSn    0x00001
#define WCSHDO_TPCn_ka  0x00002
#define WCSHDO_PVn_ma   0x00004
#define WCSHDO_CRPXna   0x00008
#define WCSHDO_CNAMna   0x00010
#define WCSHDO_WCSNna   0x00020
#define WCSHDO_P12      0x01000
#define WCSHDO_P13      0x02000
#define WCSHDO_P14      0x04000
#define WCSHDO_P15      0x08000
#define WCSHDO_P16      0x10000
#define WCSHDO_P17      0x20000
#define WCSHDO_EFMT     0x40000


extern const char *wcshdr_errmsg[];

enum wcshdr_errmsg_enum {
  WCSHDRERR_SUCCESS            = 0,	// Success.
  WCSHDRERR_NULL_POINTER       = 1,	// Null wcsprm pointer passed.
  WCSHDRERR_MEMORY             = 2,	// Memory allocation failed.
  WCSHDRERR_BAD_COLUMN         = 3,	// Invalid column selection.
  WCSHDRERR_PARSER             = 4,	// Fatal error returned by Flex
					// parser.
  WCSHDRERR_BAD_TABULAR_PARAMS = 5 	// Invalid tabular parameters.
};

int wcspih(char *header, int nkeyrec, int relax, int ctrl, int *nreject,
           int *nwcs, struct wcsprm **wcs);

int wcsbth(char *header, int nkeyrec, int relax, int ctrl, int keysel,
           int *colsel, int *nreject, int *nwcs, struct wcsprm **wcs);

int wcstab(struct wcsprm *wcs);

int wcsidx(int nwcs, struct wcsprm **wcs, int alts[27]);

int wcsbdx(int nwcs, struct wcsprm **wcs, int type, short alts[1000][28]);

int wcsvfree(int *nwcs, struct wcsprm **wcs);

int wcshdo(int ctrl, struct wcsprm *wcs, int *nkeyrec, char **header);


#ifdef __cplusplus
}
#endif

#endif // WCSLIB_WCSHDR
@


8.6
log
@WCSLIB 8.6
@
text
@d2 1
a2 1
  WCSLIB 8.6 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 8.5.1.2 2026/03/29 13:36:16 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.6 - C routines that implement the FITS World Coordinate System
@


8.6.1.1
log
@WCSLIB 8.6 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 8.6 2026/03/29 13:53:56 mcalabre Exp $
@


8.5
log
@WCSLIB 8.5
@
text
@d2 2
a3 2
  WCSLIB 8.5 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2025, Mark Calabretta
d21 2
a22 2
  http://www.atnf.csiro.au/people/Mark.Calabretta
  $Id: wcshdr.h,v 8.4.1.2 2025/12/06 13:37:16 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.5 - C routines that implement the FITS World Coordinate System
d47 1
a47 1
=   available from http://www.atnf.csiro.au/people/Mark.Calabretta
@


8.5.1.1
log
@WCSLIB 8.5 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 8.5 2025/12/06 13:47:41 mcalabre Exp $
@


8.5.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2026, Mark Calabretta
d21 2
a22 2
  http://www.atnf.csiro.au/computing/software/wcs
  $Id: wcshdr.h,v 8.5.1.1 2025/12/06 14:05:15 mcalabre Exp mcalabre $
d47 1
a47 1
=   available from http://www.atnf.csiro.au/computing/software/wcs
@


8.4
log
@WCSLIB 8.4
@
text
@d2 2
a3 2
  WCSLIB 8.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2024, Mark Calabretta
d22 1
a22 1
  $Id: wcshdr.h,v 8.3.1.1 2024/05/13 16:35:39 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.4 - C routines that implement the FITS World Coordinate System
@


8.4.1.1
log
@WCSLIB 8.4 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 8.4 2024/10/28 13:56:16 mcalabre Exp $
@


8.4.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2025, Mark Calabretta
d22 1
a22 1
  $Id: wcshdr.h,v 8.4.1.1 2024/10/28 13:58:41 mcalabre Exp mcalabre $
@


8.3
log
@WCSLIB 8.3
@
text
@d2 1
a2 1
  WCSLIB 8.3 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 8.2.1.2 2024/04/02 14:01:58 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.3 - C routines that implement the FITS World Coordinate System
@


8.3.1.1
log
@WCSLIB 8.3 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 8.3 2024/05/13 16:33:00 mcalabre Exp $
@


8.2
log
@WCSLIB 8.2
@
text
@d2 2
a3 2
  WCSLIB 8.2 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2023, Mark Calabretta
d22 1
a22 1
  $Id: wcshdr.h,v 8.1.1.1 2023/07/05 17:15:00 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.2 - C routines that implement the FITS World Coordinate System
@


8.2.1.1
log
@WCSLIB 8.2 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 8.2 2023/11/16 10:00:29 mcalabre Exp $
@


8.2.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2024, Mark Calabretta
d22 1
a22 1
  $Id: wcshdr.h,v 8.2.1.1 2023/11/16 10:05:57 mcalabre Exp mcalabre $
@


8.1
log
@WCSLIB 8.1
@
text
@d2 1
a2 1
  WCSLIB 8.1 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 8.0.1.1 2023/07/01 06:22:44 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.1 - C routines that implement the FITS World Coordinate System
@


8.1.1.1
log
@WCSLIB 8.1 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 8.1 2023/07/05 17:12:07 mcalabre Exp $
@


8.0
log
@WCSLIB 8.0
@
text
@d2 1
a2 1
  WCSLIB 8.0 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.13.1.2 2023/06/15 04:17:19 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.0 - C routines that implement the FITS World Coordinate System
@


8.0.1.1
log
@WCSLIB 8.0 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 8.0 2023/07/01 06:15:04 mcalabre Exp $
@


7.13
log
@WCSLIB 7.13
@
text
@d2 2
a3 2
  WCSLIB 7.13 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2022, Mark Calabretta
d22 1
a22 1
  $Id: wcshdr.h,v 7.12.1.1 2022/09/09 05:00:36 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.13 - C routines that implement the FITS World Coordinate System
@


7.13.1.1
log
@WCSLIB 7.13 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.13 2022/10/07 03:43:35 mcalabre Exp $
@


7.13.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2023, Mark Calabretta
d22 1
a22 1
  $Id: wcshdr.h,v 7.13.1.1 2022/10/07 03:45:47 mcalabre Exp mcalabre $
@


7.12
log
@WCSLIB 7.12
@
text
@d2 1
a2 1
  WCSLIB 7.12 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.11.1.1 2022/04/26 06:15:32 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.12 - C routines that implement the FITS World Coordinate System
@


7.12.1.1
log
@WCSLIB 7.12 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.12 2022/09/09 04:57:58 mcalabre Exp $
@


7.11
log
@WCSLIB 7.11
@
text
@d2 1
a2 1
  WCSLIB 7.11 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.10.1.1 2022/04/23 14:26:54 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.11 - C routines that implement the FITS World Coordinate System
@


7.11.1.1
log
@WCSLIB 7.11 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.11 2022/04/26 06:13:52 mcalabre Exp $
@


7.10
log
@WCSLIB 7.10
@
text
@d2 1
a2 1
  WCSLIB 7.10 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.9.1.2 2022/04/22 14:10:34 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.10 - C routines that implement the FITS World Coordinate System
@


7.10.1.1
log
@WCSLIB 7.10 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.10 2022/04/23 14:25:15 mcalabre Exp $
@


7.9
log
@WCSLIB 7.9
@
text
@d2 1
a2 1
  WCSLIB 7.9 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.8.1.1 2022/03/25 06:14:14 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.9 - C routines that implement the FITS World Coordinate System
d129 1
a129 1
* functions, which may only exist in a primary image header.
@


7.9.1.1
log
@WCSLIB 7.9 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.9 2022/03/25 15:14:48 mcalabre Exp $
@


7.9.1.2
log
@Corrected a comment in the prologue; distortion parameters are allowed in
an image extension header as well as a primary image header.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.9.1.1 2022/03/25 15:16:40 mcalabre Exp mcalabre $
d129 1
a129 1
* functions, which may only exist in an image header (primary or extension).
@


7.8
log
@WCSLIB 7.8
@
text
@d2 1
a2 1
  WCSLIB 7.8 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.7.1.2 2022/03/25 06:05:59 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.8 - C routines that implement the FITS World Coordinate System
@


7.8.1.1
log
@WCSLIB 7.8 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.8 2022/03/25 06:11:49 mcalabre Exp $
@


7.7
log
@WCSLIB 7.7
@
text
@d2 2
a3 2
  WCSLIB 7.7 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2021, Mark Calabretta
d22 1
a22 1
  $Id: wcshdr.h,v 7.6.1.1 2021/04/13 13:00:35 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.7 - C routines that implement the FITS World Coordinate System
@


7.7.1.1
log
@WCSLIB 7.7 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.7 2021/07/12 06:36:49 mcalabre Exp $
@


7.7.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2022, Mark Calabretta
d22 1
a22 1
  $Id: wcshdr.h,v 7.7.1.1 2021/07/12 06:38:27 mcalabre Exp mcalabre $
@


7.6
log
@WCSLIB 7.6
@
text
@d2 1
a2 1
  WCSLIB 7.6 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.5.1.1 2021/03/20 05:56:42 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.6 - C routines that implement the FITS World Coordinate System
@


7.6.1.1
log
@WCSLIB 7.6 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.6 2021/04/13 12:57:01 mcalabre Exp $
@


7.5
log
@WCSLIB 7.5
@
text
@d2 1
a2 1
  WCSLIB 7.5 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.4.1.1 2021/01/31 02:26:24 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.5 - C routines that implement the FITS World Coordinate System
@


7.5.1.1
log
@WCSLIB 7.5 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.5 2021/03/20 05:54:58 mcalabre Exp $
@


7.4
log
@WCSLIB 7.4
@
text
@d2 1
a2 1
  WCSLIB 7.4 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcshdr.h,v 7.3.1.5 2021/01/29 11:36:26 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.4 - C routines that implement the FITS World Coordinate System
@


7.4.1.1
log
@WCSLIB 7.4 development branch.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.4 2021/01/31 02:24:51 mcalabre Exp $
@


7.3
log
@WCSLIB 7.3
@
text
@d2 2
a3 3

  WCSLIB 7.3 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2020, Mark Calabretta
a19 2
  Direct correspondence concerning WCSLIB to mark@@calabretta.id.au

d22 1
a22 1
  $Id: wcshdr.h,v 7.2.1.2 2020/06/02 08:50:07 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.3 - C routines that implement the FITS World Coordinate System
d227 1
a227 1
*   Refer to wcsbth() notes 1, 2, 3, 5, 7, and 8.
d1177 4
a1180 4
*   wcshdo() interprets the "relax" argument as a vector of flag bits to
*   provide fine-grained control over what non-standard WCS keywords to write.
*   The flag bits are subject to change in future and should be set by using
*   the preprocessor macros (see below) for the purpose.
d1182 1
a1182 1
*   - WCSHDO_none: Don't use any extensions.
d1184 2
a1185 2
*   - WCSHDO_all: Write all recognized extensions, equivalent to setting each
*           flag bit.
d1187 2
a1188 2
*   - WCSHDO_safe: Write all extensions that are considered to be safe and
*           recommended.
d1190 7
a1196 6
*   - WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS for
*           use in binary tables and pixel lists.  WCS Paper III introduced
*           DATE-AVG and DAVGn but by an oversight DOBSn (the obvious analogy)
*           was never formally defined by the standard.  The alternative to
*           using DOBSn is to write DATE-OBS which applies to the whole table.
*           This usage is considered to be safe and is recommended.
d1198 1
a1198 1
*   - WCSHDO_TPCn_ka: WCS Paper I defined
d1200 1
a1200 1
*           - TPn_ka and TCn_ka for pixel lists
d1202 2
a1203 2
*           but WCS Paper II uses TPCn_ka in one example and subsequently the
*           errata for the WCS papers legitimized the use of
d1205 1
a1205 1
*           - TPCn_ka and TCDn_ka for pixel lists
d1207 3
a1209 3
*           provided that the keyword does not exceed eight characters.  This
*           usage is considered to be safe and is recommended because of the
*           non-mnemonic terseness of the shorter forms.
d1211 1
a1211 1
*   - WCSHDO_PVn_ma: WCS Paper I defined
d1213 2
a1214 2
*           - iVn_ma and iSn_ma for bintables and
*           - TVn_ma and TSn_ma for pixel lists
d1216 3
a1218 2
*           but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and
*           subsequently the errata for the WCS papers legitimized the use of
d1220 2
a1221 2
*           - iPVn_ma and iPSn_ma for bintables and
*           - TPVn_ma and TPSn_ma for pixel lists
d1223 3
a1225 3
*           provided that the keyword does not exceed eight characters.  This
*           usage is considered to be safe and is recommended because of the
*           non-mnemonic terseness of the shorter forms.
d1227 1
a1227 1
*   - WCSHDO_CRPXna: For historical reasons WCS Paper I defined
d1229 2
a1230 2
*           - jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn for bintables and
*           - TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists
d1232 4
a1235 3
*           for use without an alternate version specifier.  However, because
*           of the eight-character keyword constraint, in order to accommodate
*           column numbers greater than 99 WCS Paper I also defined
d1237 2
a1238 2
*           - jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and
*           - TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists
d1240 6
a1245 6
*           for use with an alternate version specifier (the "a").  Like the
*           PC, CD, PV, and PS keywords there is an obvious tendency to
*           confuse these two forms for column numbers up to 99.  It is very
*           unlikely that any parser would reject keywords in the first set
*           with a non-blank alternate version specifier so this usage is
*           considered to be safe and is recommended.
d1247 1
a1247 1
*   - WCSHDO_CNAMna: WCS Papers I and III defined
d1249 2
a1250 2
*           - iCNAna,  iCRDna,  and iCSYna  for bintables and
*           - TCNAna,  TCRDna,  and TCSYna  for pixel lists
d1252 1
a1252 1
*           By analogy with the above, the long forms would be
d1254 2
a1255 2
*           - iCNAMna, iCRDEna, and iCSYEna for bintables and
*           - TCNAMna, TCRDEna, and TCSYEna for pixel lists
d1257 4
a1260 3
*           Note that these keywords provide auxiliary information only, none
*           of them are needed to compute world coordinates.  This usage is
*           potentially unsafe and is not recommended at this time.
d1262 5
a1266 4
*   - WCSHDO_WCSNna: In light of wcsbth() note 4, write WCSNna instead of
*           TWCSna for pixel lists.  While wcsbth() treats WCSNna and TWCSna
*           as equivalent, other parsers may not.  Consequently, this usage
*           is potentially unsafe and is not recommended at this time.
d1335 7
a1341 7
  WCSHDRERR_SUCCESS            = 0,	/* Success. */
  WCSHDRERR_NULL_POINTER       = 1,	/* Null wcsprm pointer passed. */
  WCSHDRERR_MEMORY             = 2,	/* Memory allocation failed. */
  WCSHDRERR_BAD_COLUMN         = 3,	/* Invalid column selection. */
  WCSHDRERR_PARSER             = 4,	/* Fatal error returned by Flex
					   parser. */
  WCSHDRERR_BAD_TABULAR_PARAMS = 5 	/* Invalid tabular parameters. */
d1365 1
a1365 1
#endif /* WCSLIB_WCSHDR */
@


7.3.1.1
log
@WCSLIB 7.3 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 7.3 2020/06/03 03:37:02 mcalabre Exp $
@


7.3.1.2
log
@Switched to C99 style commenting (i.e. using //) within the code.
@
text
@d2 1
d25 1
a25 1
  $Id: wcshdr.h,v 7.3.1.1 2020/06/03 03:38:10 mcalabre Exp mcalabre $
d1333 7
a1339 7
  WCSHDRERR_SUCCESS            = 0,	// Success.
  WCSHDRERR_NULL_POINTER       = 1,	// Null wcsprm pointer passed.
  WCSHDRERR_MEMORY             = 2,	// Memory allocation failed.
  WCSHDRERR_BAD_COLUMN         = 3,	// Invalid column selection.
  WCSHDRERR_PARSER             = 4,	// Fatal error returned by Flex
					// parser.
  WCSHDRERR_BAD_TABULAR_PARAMS = 5 	// Invalid tabular parameters.
d1363 1
a1363 1
#endif // WCSLIB_WCSHDR
@


7.3.1.3
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2021, Mark Calabretta
d24 1
a24 1
  $Id: wcshdr.h,v 7.3.1.2 2020/08/17 11:19:09 mcalabre Exp mcalabre $
@


7.3.1.4
log
@Removed my email address from the copyright notice.
@
text
@d20 2
d24 1
a24 1
  $Id: wcshdr.h,v 7.3.1.3 2021/01/19 14:09:10 mcalabre Exp mcalabre $
@


7.3.1.5
log
@Numbered entries in the Notes section in the prologue so that they will be
indented properly in the manual.
@
text
@d22 1
a22 1
  $Id: wcshdr.h,v 7.3.1.4 2021/01/28 12:29:30 mcalabre Exp mcalabre $
d227 1
a227 1
*   1: Refer to wcsbth() notes 1, 2, 3, 5, 7, and 8.
d1177 4
a1180 4
*   1: wcshdo() interprets the "relax" argument as a vector of flag bits to
*      provide fine-grained control over what non-standard WCS keywords to
*      write.  The flag bits are subject to change in future and should be set
*      by using the preprocessor macros (see below) for the purpose.
d1182 1
a1182 1
*      - WCSHDO_none: Don't use any extensions.
d1184 2
a1185 2
*      - WCSHDO_all: Write all recognized extensions, equivalent to setting
*              each flag bit.
d1187 2
a1188 2
*      - WCSHDO_safe: Write all extensions that are considered to be safe and
*              recommended.
d1190 6
a1195 7
*      - WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS
*              for use in binary tables and pixel lists.  WCS Paper III
*              introduced DATE-AVG and DAVGn but by an oversight DOBSn (the
*              obvious analogy) was never formally defined by the standard.
*              The alternative to using DOBSn is to write DATE-OBS which
*              applies to the whole table.  This usage is considered to be
*              safe and is recommended.
d1197 1
a1197 1
*      - WCSHDO_TPCn_ka: WCS Paper I defined
d1199 1
a1199 1
*              - TPn_ka and TCn_ka for pixel lists
d1201 2
a1202 2
*              but WCS Paper II uses TPCn_ka in one example and subsequently
*              the errata for the WCS papers legitimized the use of
d1204 1
a1204 1
*              - TPCn_ka and TCDn_ka for pixel lists
d1206 3
a1208 3
*              provided that the keyword does not exceed eight characters.
*              This usage is considered to be safe and is recommended because
*              of the non-mnemonic terseness of the shorter forms.
d1210 1
a1210 1
*      - WCSHDO_PVn_ma: WCS Paper I defined
d1212 2
a1213 2
*              - iVn_ma and iSn_ma for bintables and
*              - TVn_ma and TSn_ma for pixel lists
d1215 2
a1216 3
*              but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and
*              subsequently the errata for the WCS papers legitimized the use
*              of
d1218 2
a1219 2
*              - iPVn_ma and iPSn_ma for bintables and
*              - TPVn_ma and TPSn_ma for pixel lists
d1221 3
a1223 3
*              provided that the keyword does not exceed eight characters.
*              This usage is considered to be safe and is recommended because
*              of the non-mnemonic terseness of the shorter forms.
d1225 1
a1225 1
*      - WCSHDO_CRPXna: For historical reasons WCS Paper I defined
d1227 2
a1228 2
*              - jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn for bintables and
*              - TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists
d1230 3
a1232 4
*              for use without an alternate version specifier.  However,
*              because of the eight-character keyword constraint, in order to
*              accommodate column numbers greater than 99 WCS Paper I also
*              defined
d1234 2
a1235 2
*              - jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and
*              - TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists
d1237 6
a1242 6
*              for use with an alternate version specifier (the "a").  Like
*              the PC, CD, PV, and PS keywords there is an obvious tendency to
*              confuse these two forms for column numbers up to 99.  It is
*              very unlikely that any parser would reject keywords in the
*              first set with a non-blank alternate version specifier so this
*              usage is considered to be safe and is recommended.
d1244 1
a1244 1
*      - WCSHDO_CNAMna: WCS Papers I and III defined
d1246 2
a1247 2
*              - iCNAna,  iCRDna,  and iCSYna  for bintables and
*              - TCNAna,  TCRDna,  and TCSYna  for pixel lists
d1249 1
a1249 1
*              By analogy with the above, the long forms would be
d1251 2
a1252 2
*              - iCNAMna, iCRDEna, and iCSYEna for bintables and
*              - TCNAMna, TCRDEna, and TCSYEna for pixel lists
d1254 3
a1256 4
*              Note that these keywords provide auxiliary information only,
*              none of them are needed to compute world coordinates.  This
*              usage is potentially unsafe and is not recommended at this
*              time.
d1258 4
a1261 5
*      - WCSHDO_WCSNna: In light of wcsbth() note 4, write WCSNna instead of
*              TWCSna for pixel lists.  While wcsbth() treats WCSNna and
*              TWCSna as equivalent, other parsers may not.  Consequently,
*              this usage is potentially unsafe and is not recommended at this
*              time.
@


7.2
log
@WCSLIB 7.2
@
text
@d3 1
a3 1
  WCSLIB 7.2 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 7.1.1.1 2019/12/31 13:28:19 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 7.2 - C routines that implement the FITS World Coordinate System
d540 7
d1302 5
a1306 4
#define WCSHDR_LONGKEY  0x00004000
#define WCSHDR_CNAMn    0x00008000
#define WCSHDR_AUXIMG   0x00010000
#define WCSHDR_ALLIMG   0x00020000
@


7.2.1.1
log
@WCSLIB 7.2 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 7.2 2020/03/09 07:31:23 mcalabre Exp $
@


7.2.1.2
log
@Added WCSHDR_DATEREF to the flags that control acceptance of non-standard
keywords by wcspih() and wcsbth().
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 7.2.1.1 2020/03/09 07:34:50 mcalabre Exp mcalabre $
a539 7
*      - WCSHDR_DATEREF: Accept DATE-REF, MJD-REF, MJD-REFI, MJD-REFF, JDREF,
*              JD-REFI, and JD-REFF as synonyms for the standard keywords,
*              DATEREF, MJDREF, MJDREFI, MJDREFF, JDREF, JDREFI, and JDREFF.
*              The latter buck the pattern set by the other date keywords
*              ({DATE,MJD}-{OBS,BEG,AVG,END}), thereby increasing the
*              potential for confusion and error.
*
d1295 4
a1298 5
#define WCSHDR_DATEREF  0x00004000
#define WCSHDR_LONGKEY  0x00008000
#define WCSHDR_CNAMn    0x00010000
#define WCSHDR_AUXIMG   0x00020000
#define WCSHDR_ALLIMG   0x00040000
@


7.1
log
@WCSLIB 7.1
@
text
@d3 1
a3 1
  WCSLIB 7.1 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 6.4.1.2 2019/12/31 03:28:03 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 7.1 - C routines that implement the FITS World Coordinate System
@


7.1.1.1
log
@WCSLIB 7.1 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 7.1 2019/12/31 13:25:19 mcalabre Exp $
@


6.4
log
@WCSLIB 6.4
@
text
@d3 2
a4 2
  WCSLIB 6.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2019, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 6.3.1.1 2019/07/12 07:34:37 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.4 - C routines that implement the FITS World Coordinate System
@


6.4.1.1
log
@WCSLIB 6.4 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 6.4 2019/08/15 09:30:18 mcalabre Exp $
@


6.4.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2020, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 6.4.1.1 2019/08/15 09:31:29 mcalabre Exp mcalabre $
@


6.3
log
@WCSLIB 6.3
@
text
@d3 1
a3 1
  WCSLIB 6.3 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 6.2.1.3 2019/07/11 05:05:59 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.3 - C routines that implement the FITS World Coordinate System
@


6.3.1.1
log
@WCSLIB 6.3 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 6.3 2019/07/12 07:33:39 mcalabre Exp $
@


6.2
log
@WCSLIB 6.2
@
text
@d3 2
a4 2
  WCSLIB 6.2 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2018, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 6.1.1.2 2018/10/20 09:38:53 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.2 - C routines that implement the FITS World Coordinate System
d75 1
a75 1
*        free'd by wcsfree().
d912 1
a912 1
* particular causing it to be free'd by wcsfree(); the user must not attempt
d924 1
a924 1
*                       memory will be free'd automatically by wcsfree().
d1149 2
a1150 1
*                       and must be free'd by the user to avoid memory leaks.
@


6.2.1.1
log
@WCSLIB 6.2 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 6.2 2018/10/20 10:03:13 mcalabre Exp $
@


6.2.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2019, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 6.2.1.1 2018/10/20 10:04:15 mcalabre Exp mcalabre $
@


6.2.1.3
log
@free'd -> freed.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 6.2.1.2 2019/05/10 01:56:50 mcalabre Exp mcalabre $
d75 1
a75 1
*        freed by wcsfree().
d912 1
a912 1
* particular causing it to be freed by wcsfree(); the user must not attempt
d924 1
a924 1
*                       memory will be freed automatically by wcsfree().
d1149 1
a1149 2
*                       and must be freed by the user to avoid memory leaks.
*                       See wcsdealloc().
@


6.1
log
@WCSLIB 6.1
@
text
@d3 1
a3 1
  WCSLIB 6.1 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.20.1.2 2018/10/19 07:28:12 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.1 - C routines that implement the FITS World Coordinate System
d612 1
a612 1
*
d646 1
a646 1
*
d659 1
a659 1
*
d664 1
a664 1
*
d744 1
a744 1
*
d875 1
a875 1
*      OBSGXn, OBXGYn, and OBSGZn which are meant to define the elements of a
d1347 1
a1347 1
int wcshdo(int relax, struct wcsprm *wcs, int *nkeyrec, char **header);
@


6.1.1.1
log
@WCSLIB 6.1 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 6.1 2018/10/19 08:35:17 mcalabre Exp $
@


6.1.1.2
log
@Fix for doxygen manual generation - changed the argument names in the
wcshdo() prototype to match those documented in the prologue.  Other minor
formatting tweaks for doxygen.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 6.1.1.1 2018/10/19 08:36:15 mcalabre Exp mcalabre $
d612 1
a612 1
#
d646 1
a646 1
#
d659 1
a659 1
#
d664 1
a664 1
#
d744 1
a744 1
#
d875 1
a875 1
*      OBSGXn, OBSGYn, and OBSGZn which are meant to define the elements of a
d1347 1
a1347 1
int wcshdo(int ctrl, struct wcsprm *wcs, int *nkeyrec, char **header);
@


5.20
log
@WCSLIB 5.20
@
text
@d3 1
a3 1
  WCSLIB 5.20 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.19.1.1 2018/07/26 15:41:40 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.20 - C routines that implement the FITS World Coordinate System
d51 5
d116 5
a120 3
* defined in Papers I, II, and III are recognized, and also those used by the
* AIPS convention and certain other keywords that existed in early drafts of
* the WCS papers as explained in wcsbth() note 5.
d131 2
a132 1
* headers.
d188 4
a191 2
*                         -11: Same as -1 but preserving the basic keywords
*                              '{DATE,MJD}-{OBS,AVG}' and 'OBSGEO-{X,Y,Z}'.
d248 3
a250 3
* All WCS keywords defined in Papers I, II, and III are recognized, and also
* those used by the AIPS convention and certain other keywords that existed in
* early drafts of the WCS papers as explained in note 5 below.
d322 4
a325 2
*                         -11: Same as -1 but preserving the basic keywords
*                              '{DATE,MJD}-{OBS,AVG}' and 'OBSGEO-{X,Y,Z}'.
d434 2
a435 2
*      defined in WCS Papers II and III that are not parameterized by axis
*      number have identical forms for binary tables and pixel lists.
a485 1
*      - WCSHDR_EPOCHa:  Accept EPOCHa.
d516 9
d531 2
a539 4
*      - WCSHDR_DOBSn (wcsbth() only): Allow DOBSn, the column-specific
*              analogue of DATE-OBS.  By an oversight this was never formally
*              defined in the standard.
*
d576 2
d579 8
a586 7
*              Note that CNAMEia, CRDERia, CSYERia, and their variants are
*              not used by WCSLIB but are stored in the wcsprm struct as
*              auxiliary information.
*
*      - WCSHDR_CNAMn (wcsbth() only): Accept iCNAMn, iCRDEn, iCSYEn, TCNAMn,
*              TCRDEn, and TCSYEn, i.e. with "a" blank.  While non-standard,
*              these are the obvious analogues of iCTYPn, TCTYPn, etc.
d599 1
d601 2
a602 4
#                LONPOLEa  for LONPna
#                RESTFREQ  for RFRQna
#                RESTFRQa  for RFRQna
#                RESTWAVa  for RWAVna
d605 2
a606 2
*              that provide auxiliary information that is simply stored in
*              the wcsprm struct:
d608 7
a617 12
#                RADESYSa  for RADEna
#                RADECSYS  for RADEna  ... Only if WCSHDR_RADECSYS is set.
#                SPECSYSa  for SPECna
#                SSYSOBSa  for SOBSna
#                SSYSSRCa  for SSRCna
#                VELOSYSa  for VSYSna
#                VELANGLa  for VANGna
#                VELREF        -       ... (No column-specific form.)
#                VELREFa       -       ... Only if WCSHDR_VELREFa is set.
#                VSOURCEa  for VSOUna  ... Only if WCSHDR_VSOURCE is set.
#                WCSNAMEa  for WCSNna  ... Or TWCSna (see below).
#                ZSOURCEa  for ZSOUna
d619 29
d649 2
a650 1
#                DATE-OBS  for DOBSn
d652 13
a664 1
#                MJD-OBS   for MJDOBn
d668 12
d681 3
a683 6
*              where the image-header keywords on the left provide default
*              values for the column specific keywords on the right.
*
*              Keywords in the last group, such as MJD-OBS, apply to all
*              alternate representations, so MJD-OBS would provide a default
*              value for all images in the header.
d689 17
a705 3
*              defaults for each other.  Thus the only potential difficulty
*              in using WCSHDR_AUXIMG is that of erroneously inheriting one
*              of these four keywords.
d712 2
a713 2
*              conjunction with the default values of those keywords, such as
*              CTYPEia, that are parameterized by axis number.
d731 1
a731 1
*              keywords which are parameterized by axis number:
d748 2
d757 1
a757 1
*              number and column number.
d833 2
a834 1
*      neutrino.
d836 5
a840 5
*      In the absence of a formal mechanism for identifying the columns
*      containing pixel coordinates (as opposed to pixel values or ancillary
*      data recorded at the time the photon or neutrino was detected),
*      Paper I discusses how the WCS keywords themselves may be used to
*      identify them.
d843 45
a887 13
*      images.  Besides not specifying how to identify columns, the pixel
*      list convention is also silent on the method to be used to associate
*      table columns with image axes.
*
*      wcsbth() simply collects all WCS keywords for a particular coordinate
*      representation (i.e. the "a" value in TCTYna) into one wcsprm struct.
*      However, these alternates need not be associated with the same table
*      columns and this allows a pixel list to contain up to 27 separate
*      images.  As usual, if one of these representations happened to contain
*      more than two celestial axes, for example, then an error would result
*      when wcsset() is invoked on it.  In this case the "colsel" argument
*      could be used to restrict the columns used to construct the
*      representation so that it only contained one pair of celestial axes.
d905 2
a906 2
* the prologue of wcs.h) to assist in extracting the required arrays from the
* BINTABLE extension(s).
a1049 8
*   - Deprecated (e.g. CROTAn) or non-standard usage will be translated to
*     standard (this is partially dependent on whether wcsfix() was applied).
*
*   - Quantities will be converted to the units used internally, basically SI
*     with the addition of degrees.
*
*   - Floating-point quantities may be given to a different decimal precision.
*
d1054 8
d1065 5
d1073 1
a1073 1
*   - Keyword order may be changed.
d1281 17
a1297 16
#define WCSHDR_EPOCHa   0x00000002
#define WCSHDR_VELREFa  0x00000004
#define WCSHDR_CD00i00j 0x00000008
#define WCSHDR_PC00i00j 0x00000010
#define WCSHDR_PROJPn   0x00000020
#define WCSHDR_CD0i_0ja 0x00000040
#define WCSHDR_PC0i_0ja 0x00000080
#define WCSHDR_PV0i_0ma 0x00000100
#define WCSHDR_PS0i_0ma 0x00000200
#define WCSHDR_RADECSYS 0x00000400
#define WCSHDR_VSOURCE  0x00000800
#define WCSHDR_DOBSn    0x00001000
#define WCSHDR_LONGKEY  0x00002000
#define WCSHDR_CNAMn    0x00004000
#define WCSHDR_AUXIMG   0x00008000
#define WCSHDR_ALLIMG   0x00010000
@


5.20.1.1
log
@WCSLIB 5.20 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.20 2018/10/05 05:32:41 mcalabre Exp $
@


5.20.1.2
log
@Added support for time-related WCS keywords (Paper VII).  In the notes for
wcsbth(), clarified that, according to WCS Papers III and VII, certain global
image header keywords are permitted in binary table headers and are expected
to be inherited by image arrays and pixel lists.  Elaborated on the
difficulties that such inheritance may cause for pixel lists.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.20.1.1 2018/10/05 05:33:33 mcalabre Exp mcalabre $
a50 5
=
=   "Representations of time coordinates in FITS -
=    Time and relative dimension in space",
=   Rots, A.H., Bunclark, P.S., Calabretta, M.R., Allen, S.L.,
=   Manchester, R.N., & Thompson, W.T. 2015, A&A, 574, A36 (WCS Paper VII)
d111 3
a113 5
* defined in Papers I, II, III, IV, and VII are recognized, and also those
* used by the AIPS convention and certain other keywords that existed in early
* drafts of the WCS papers as explained in wcsbth() note 5.  wcspih() also
* handles keywords associated with non-standard distortion functions described
* in the prologue of dis.h.
d124 1
a124 2
* headers, although it cannot handle keywords relating to distortion
* functions, which may only exist in a primary image header.
d180 2
a181 4
*                         -11: Same as -1 but preserving global WCS-related
*                              keywords such as '{DATE,MJD}-{OBS,BEG,AVG,END}'
*                              and the other basic time-related keywords, and
*                              'OBSGEO-{X,Y,Z,L,B,H}'.
d238 3
a240 3
* All WCS keywords defined in Papers I, II, III, and VII are recognized, and
* also those used by the AIPS convention and certain other keywords that
* existed in early drafts of the WCS papers as explained in note 5 below.
d312 2
a313 4
*                         -11: Same as -1 but preserving global WCS-related
*                              keywords such as '{DATE,MJD}-{OBS,BEG,AVG,END}'
*                              and the other basic time-related keywords, and
*                              'OBSGEO-{X,Y,Z,L,B,H}'.
d422 2
a423 2
*      defined in WCS Papers II, III, and VII that are not parameterized by
*      axis number have identical forms for binary tables and pixel lists.
d474 1
a504 9
*      - WCSHDR_DOBSn (wcsbth() only): Allow DOBSn, the column-specific
*              analogue of DATE-OBS.  By an oversight this was never formally
*              defined in the standard.
*
*      - WCSHDR_OBSGLBHn (wcsbth() only): Allow OBSGLn, OBSGBn, and OBSGHn,
*              the column-specific analogues of OBSGEO-L, OBSGEO-B, and
*              OBSGEO-H.  By an oversight these were never formally defined in
*              the standard.
*
a510 2
*      - WCSHDR_EPOCHa:  Accept EPOCHa.
*
d518 4
a557 2
#                iCZPHna  TCZPHna  :   ---   iCZPna    ---   TCZPna  CZPHSia
#                iCPERna  TCPERna  :   ---   iCPRna    ---   TCPRna  CPERIia
d559 7
a565 8
*              Note that CNAMEia, CRDERia, CSYERia, CZPHSia, CPERIia, and
*              their variants are not used by WCSLIB but are stored in the
*              wcsprm struct as auxiliary information.
*
*      - WCSHDR_CNAMn (wcsbth() only): Accept iCNAMn, iCRDEn, iCSYEn, iCZPHn,
*              iCPERn, TCNAMn, TCRDEn, TCSYEn, TCZPHn, and TCPERn, i.e. with
*              "a" blank.  While non-standard, these are the obvious analogues
*              of iCTYPn, TCTYPn, etc.
d578 1
d580 3
a582 3
#                LATPOLEa  for LATPna
#                VELREF        -       ... (No column-specific form.)
#                VELREFa       -       ... Only if WCSHDR_VELREFa is set.
d585 2
a586 2
*              providing auxiliary information that is simply stored in the
*              wcsprm struct:
a587 7
#                WCSNAMEa  for WCSNna  ... Or TWCSna (see below).
#
#                DATE-OBS  for DOBSn
#                MJD-OBS   for MJDOBn
*
#                RADESYSa  for RADEna
#                RADECSYS  for RADEna  ... Only if WCSHDR_RADECSYS is set.
d591 12
a603 29
*              where the image-header keywords on the left provide default
*              values for the column specific keywords on the right.
*
*              Note that, according to Sect. 8.1 of WCS Paper III, and
*              Sect. 5.2 of WCS Paper VII, the following are always inherited:
*
#                RESTFREQ  for RFRQna
#                RESTFRQa  for RFRQna
#                RESTWAVa  for RWAVna
*
*              being those actually used by WCSLIB, together with the
*              following auxiliary keywords, many of which do not have binary
*              table equivalents and therefore can only be inherited:
*
#                TIMESYS       -
#                TREFPOS   for TRPOSn
#                TREFDIR   for TRDIRn
#                PLEPHEM       -
#                TIMEUNIT      -
#                DATEREF       -
#                MJDREF        -
#                MJDREFI       -
#                MJDREFF       -
#                JDREF         -
#                JDREFI        -
#                JDREFF        -
#                TIMEOFFS      -
*
#                DATE-BEG      -
d605 1
a605 2
#                DATE-END      -
#                MJD-BEG       -
d607 1
a607 13
#                MJD-END       -
#                JEPOCH        -
#                BEPOCH        -
#                TSTART        -
#                TSTOP         -
#                XPOSURE       -
#                TELAPSE       -
*
#                TIMSYER       -
#                TIMRDER       -
#                TIMEDEL       -
#                TIMEPIXR      -
*
a610 12
#                OBSGEO-L  for OBSGLn
#                OBSGEO-B  for OBSGBn
#                OBSGEO-H  for OBSGHn
#                OBSORBIT      -
#
#                SPECSYSa  for SPECna
#                SSYSOBSa  for SOBSna
#                VELOSYSa  for VSYSna
#                VSOURCEa  for VSOUna  ... Only if WCSHDR_VSOURCE is set.
#                ZSOURCEa  for ZSOUna
#                SSYSSRCa  for SSRCna
#                VELANGLa  for VANGna
d612 6
a617 3
*              Global image-header keywords, such as MJD-OBS, apply to all
*              alternate representations, and would therefore provide a
*              default value for all images in the header.
d623 3
a625 17
*              defaults for each other.  Thus one potential difficulty in
*              using WCSHDR_AUXIMG is that of erroneously inheriting one of
*              these four keywords.
*
*              Also, beware of potential inconsistencies that may arise where,
*              for example, DATE-OBS is inherited, but MJD-OBS is overridden
*              by MJDOBn and specifies a different time.  Pairs in this
*              category are:
*
=                    DATE-OBS/DOBSn       versus       MJD-OBS/MJDOBn
=                    DATE-AVG/DAVGn       versus       MJD-AVG/MJDAn
=                    RESTFRQa/RFRQna      versus      RESTWAVa/RWAVna
=                OBSGEO-[XYZ]/OBSG[XYZ]n  versus  OBSGEO-[LBH]/OBSG[LBH]n
*
*              The wcsfixi() routines datfix() and obsfix() are provided to
*              check the consistency of these and other such pairs of
*              keywords.
d632 2
a633 2
*              conjunction with the default values of those keywords that are
*              parameterized by axis number, such as CTYPEia.
d651 1
a651 1
*              keywords that are parameterized by axis number:
a667 2
#                CZPHSia   for iCZPna
#                CPERIia   for iCPRna
d675 1
a675 1
*              number and column number (see note 9 below).
d751 1
a751 2
*      neutrino, for which the device "pixel" coordinates are stored in
*      separate scalar columns of the table.
d753 5
a757 5
*      In the absence of a standard for pixel lists - or even an informal
*      description! - let alone a formal mechanism for identifying the columns
*      containing pixel coordinates (as opposed to pixel values or metadata
*      recorded at the time the photon or neutrino was detected), WCS Paper I
*      discusses how the WCS keywords themselves may be used to identify them.
d760 13
a772 45
*      images.  Besides not specifying how to identify columns, the pixel list
*      convention is also silent on the method to be used to associate table
*      columns with image axes.
*
*      An additional shortcoming is the absence of a formal method for
*      associating global binary-table WCS keywords, such as WCSNna or MJDOBn,
*      with a pixel list image, whether one or several.
*
*      In light of these uncertainties, wcsbth() simply collects all WCS
*      keywords for a particular pixel list coordinate representation (i.e.
*      the "a" value in TCTYna) into one wcsprm struct.  However, these
*      alternates need not be associated with the same table columns and this
*      allows a pixel list to contain up to 27 separate images.  As usual, if
*      one of these representations happened to contain more than two
*      celestial axes, for example, then an error would result when wcsset()
*      is invoked on it.  In this case the "colsel" argument could be used to
*      restrict the columns used to construct the representation so that it
*      only contained one pair of celestial axes.
*
*      Global, binary-table WCS keywords are considered to apply to the pixel
*      list image with matching alternate (e.g. the "a" value in LONPna or
*      EQUIna), regardless of the table columns the image occupies.  In other
*      words, the column number is ignored (the "n" value in LONPna or
*      EQUIna).  This also applies for global, binary-table WCS keywords that
*      have no alternates, such as MJDOBn and OBSGXn, which match all images
*      in a pixel list.  Take heed that this may lead to counterintuitive
*      behaviour, especially where such a keyword references a column that
*      does not store pixel coordinates, and moreso where the pixel list
*      stores only a single image.  In fact, as the column number, n, is
*      ignored for such keywords, it would make no difference even if they
*      referenced non-existent columns.  Moreover, there is no requirement for
*      consistency in the column numbers used for such keywords, even for
*      OBSGXn, OBXGYn, and OBSGZn which are meant to define the elements of a
*      coordinate vector.  Although it would surely be perverse to construct a
*      pixel list like this, such a situation may still arise in practice
*      where columns are deleted from a binary table.
*
*      The situation with global, binary-table WCS keywords becomes
*      potentially even more confusing when image arrays and pixel list images
*      coexist in one binary table.  In that case, a keyword such as MJDOBn
*      may legitimately appear multiple times with n referencing different
*      image arrays.  Which then is the one that applies to the pixel list
*      images?  In this implementation, it is the last instance that appears
*      in the header, whether or not it is also associated with an image
*      array.
d790 2
a791 2
* the prologue of wtbarr.h) to assist in extracting the required arrays from
* the BINTABLE extension(s).
d935 8
a946 8
*   - The redundant keywords MJDREF, JDREF, JDREFI, JDREFF, all of which
*     duplicate MJDREFI + MJDREFF, are never written.  OBSGEO-[LBH] are not
*     written if OBSGEO-[XYZ] are defined.
*
*   - Deprecated (e.g. CROTAn, RESTFREQ, VELREF, RADECSYS, EPOCH, VSOURCEa) or
*     non-standard usage will be translated to standard (this is partially
*     dependent on whether wcsfix() was applied).
*
a949 5
*   - Quantities will be converted to the units used internally, basically SI
*     with the addition of degrees.
*
*   - Floating-point quantities may be given to a different decimal precision.
*
d953 1
a953 1
*   - Keyword order will almost certainly be changed.
d1161 16
a1176 17
#define WCSHDR_VELREFa  0x00000002
#define WCSHDR_CD00i00j 0x00000004
#define WCSHDR_PC00i00j 0x00000008
#define WCSHDR_PROJPn   0x00000010
#define WCSHDR_CD0i_0ja 0x00000020
#define WCSHDR_PC0i_0ja 0x00000040
#define WCSHDR_PV0i_0ma 0x00000080
#define WCSHDR_PS0i_0ma 0x00000100
#define WCSHDR_DOBSn    0x00000200
#define WCSHDR_OBSGLBHn 0x00000400
#define WCSHDR_RADECSYS 0x00000800
#define WCSHDR_EPOCHa   0x00001000
#define WCSHDR_VSOURCE  0x00002000
#define WCSHDR_LONGKEY  0x00004000
#define WCSHDR_CNAMn    0x00008000
#define WCSHDR_AUXIMG   0x00010000
#define WCSHDR_ALLIMG   0x00020000
@


5.19
log
@WCSLIB 5.19
@
text
@d3 1
a3 1
  WCSLIB 5.19 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.18.1.1 2018/01/10 08:33:04 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.19 - C routines that implement the FITS World Coordinate System
@


5.19.1.1
log
@WCSLIB 5.19 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.19 2018/07/26 15:37:04 mcalabre Exp $
@


5.18
log
@WCSLIB 5.18
@
text
@d3 1
a3 1
  WCSLIB 5.18 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.17.1.2 2018/01/10 08:25:34 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.18 - C routines that implement the FITS World Coordinate System
@


5.18.1.1
log
@WCSLIB 5.18 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.18 2018/01/10 08:32:14 mcalabre Exp $
@


5.17
log
@WCSLIB 5.17
@
text
@d3 2
a4 2
  WCSLIB 5.17 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2017, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 5.16.1.1 2017/01/15 04:28:59 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.17 - C routines that implement the FITS World Coordinate System
@


5.17.1.1
log
@WCSLIB 5.17 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.17 2017/09/18 08:44:23 mcalabre Exp $
@


5.17.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2018, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 5.17.1.1 2017/09/18 08:45:59 mcalabre Exp mcalabre $
@


5.16
log
@WCSLIB 5.16
@
text
@d3 1
a3 1
  WCSLIB 5.16 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.15.1.2 2017/01/15 04:14:00 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.16 - C routines that implement the FITS World Coordinate System
@


5.16.1.1
log
@WCSLIB 5.16 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.16 2017/01/15 04:25:01 mcalabre Exp $
@


5.15
log
@WCSLIB 5.15
@
text
@d3 2
a4 2
  WCSLIB 5.15 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2016, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 5.14.1.1 2016/02/07 10:52:44 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.15 - C routines that implement the FITS World Coordinate System
@


5.15.1.1
log
@WCSLIB 5.15 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.15 2016/04/05 12:55:10 mcalabre Exp $
@


5.15.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2017, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 5.15.1.1 2016/04/05 12:58:35 mcalabre Exp mcalabre $
@


5.14
log
@WCSLIB 5.14
@
text
@d3 1
a3 1
  WCSLIB 5.14 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.13.1.1 2016/01/26 08:54:32 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.14 - C routines that implement the FITS World Coordinate System
@


5.14.1.1
log
@WCSLIB 5.14 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.14 2016/02/07 10:49:31 mcalabre Exp $
@


5.13
log
@WCSLIB 5.13
@
text
@d3 1
a3 1
  WCSLIB 5.13 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.12.1.3 2016/01/26 08:09:41 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.13 - C routines that implement the FITS World Coordinate System
@


5.13.1.1
log
@WCSLIB 5.13 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.13 2016/01/26 08:51:13 mcalabre Exp $
@


5.12
log
@WCSLIB 5.12
@
text
@d3 2
a4 2
  WCSLIB 5.12 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2015, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 5.11.1.1 2015/10/18 09:16:27 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.12 - C routines that implement the FITS World Coordinate System
d960 11
a970 5
*   relax     int       Degree of permissiveness:
*                          0: Recognize only FITS keywords defined by the
*                             published WCS standard.
*                         -1: Admit all informal extensions of the WCS
*                             standard.
d974 42
d1182 16
a1197 9
#define WCSHDO_none     0x00
#define WCSHDO_all      0xFF
#define WCSHDO_safe     0x0F
#define WCSHDO_DOBSn    0x01
#define WCSHDO_TPCn_ka  0x02
#define WCSHDO_PVn_ma   0x04
#define WCSHDO_CRPXna   0x08
#define WCSHDO_CNAMna   0x10
#define WCSHDO_WCSNna   0x20
@


5.12.1.1
log
@WCSLIB 5.12 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.12 2015/11/15 02:13:00 mcalabre Exp $
@


5.12.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2016, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 5.12.1.1 2015/11/15 02:16:14 mcalabre Exp mcalabre $
@


5.12.1.3
log
@In wcshdo(), provide floating-point format control via the 'ctrl'
argument (formerly 'relax').
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.12.1.2 2016/01/25 05:17:04 mcalabre Exp mcalabre $
d960 5
a964 11
*   ctrl      int       Vector of flag bits that controls the degree of
*                       permissiveness in departing from the published WCS
*                       standard, and also controls the formatting of
*                       floating-point keyvalues.  Set it to zero to get the
*                       default behaviour.
*
*                       Flag bits for the degree of permissiveness:
*                         WCSHDO_none: Recognize only FITS keywords defined by
*                            the published WCS standard.
*                         WCSHDO_all: Admit all recognized informal extensions
*                            of the WCS standard.
a967 42
*                       As for controlling floating-point formatting, by
*                       default wcshdo() uses "%20.12G" for non-parameterized
*                       keywords such as LONPOLEa, and attempts to make the
*                       header more human-readable by using the same "%f"
*                       format for all values of each of the following
*                       parameterized keywords: CRPIXja, PCi_ja, and CDELTia
*                       (n.b. excluding CRVALia).  Each has the same field
*                       width and precision so that the decimal points line
*                       up.  The precision, allowing for up to 15 significant
*                       digits, is chosen so that there are no excess trailing
*                       zeroes.  A similar formatting scheme applies by
*                       default for distortion function parameters.
*
*                       However, where the values of, for example, CDELTia
*                       differ by many orders of magnitude, the default
*                       formatting scheme may cause unacceptable loss of
*                       precision for the lower-valued keyvalues.  Thus the
*                       default behaviour may be overridden:
*                         WCSHDO_P12: Use "%20.12G" format for all floating-
*                            point keyvalues (12 significant digits).
*                         WCSHDO_P13: Use "%21.13G" format for all floating-
*                            point keyvalues (13 significant digits).
*                         WCSHDO_P14: Use "%22.14G" format for all floating-
*                            point keyvalues (14 significant digits).
*                         WCSHDO_P15: Use "%23.15G" format for all floating-
*                            point keyvalues (15 significant digits).
*                         WCSHDO_P16: Use "%24.16G" format for all floating-
*                            point keyvalues (16 significant digits).
*                         WCSHDO_P17: Use "%25.17G" format for all floating-
*                            point keyvalues (17 significant digits).
*                       If more than one of the above flags are set, the
*                       highest number of significant digits prevails.  In
*                       addition, there is an anciliary flag:
*                         WCSHDO_EFMT: Use "%E" format instead of the default
*                            "%G" format above.
*                       Note that excess trailing zeroes are stripped off the
*                       fractional part with "%G" (which never occurs with
*                       "%E").  Note also that the higher-precision options
*                       eat into the keycomment area.  In this regard,
*                       WCSHDO_P14 causes minimal disruption with "%G" format,
*                       while WCSHDO_P13 is appropriate with "%E".
*
d1134 9
a1142 16
#define WCSHDO_none     0x00000
#define WCSHDO_all      0x000FF
#define WCSHDO_safe     0x0000F
#define WCSHDO_DOBSn    0x00001
#define WCSHDO_TPCn_ka  0x00002
#define WCSHDO_PVn_ma   0x00004
#define WCSHDO_CRPXna   0x00008
#define WCSHDO_CNAMna   0x00010
#define WCSHDO_WCSNna   0x00020
#define WCSHDO_P12      0x01000
#define WCSHDO_P13      0x02000
#define WCSHDO_P14      0x04000
#define WCSHDO_P15      0x08000
#define WCSHDO_P16      0x10000
#define WCSHDO_P17      0x20000
#define WCSHDO_EFMT     0x40000
@


5.11
log
@WCSLIB 5.11
@
text
@d3 1
a3 1
  WCSLIB 5.11 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.10.1.1 2015/10/09 08:22:35 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.11 - C routines that implement the FITS World Coordinate System
@


5.11.1.1
log
@WCSLIB 5.11 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.11 2015/10/18 09:13:05 mcalabre Exp $
@


5.10
log
@WCSLIB 5.10
@
text
@d3 1
a3 1
  WCSLIB 5.10 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.9.1.1 2015/07/21 09:28:07 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.10 - C routines that implement the FITS World Coordinate System
@


5.10.1.1
log
@WCSLIB 5.10 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.10 2015/10/09 08:19:15 mcalabre Exp $
@


5.9
log
@WCSLIB 5.9
@
text
@d3 1
a3 1
  WCSLIB 5.9 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.8.1.1 2015/07/08 11:07:18 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.9 - C routines that implement the FITS World Coordinate System
@


5.9.1.1
log
@WCSLIB 5.9 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.9 2015/07/21 09:20:01 mcalabre Exp $
@


5.8
log
@WCSLIB 5.8
@
text
@d3 1
a3 1
  WCSLIB 5.8 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.7.1.1 2015/06/29 02:47:24 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.8 - C routines that implement the FITS World Coordinate System
@


5.8.1.1
log
@WCSLIB 5.8 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.8 2015/07/08 11:03:59 mcalabre Exp $
@


5.7
log
@WCSLIB 5.7
@
text
@d3 1
a3 1
  WCSLIB 5.7 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.6.1.1 2015/06/14 07:14:44 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.7 - C routines that implement the FITS World Coordinate System
@


5.7.1.1
log
@WCSLIB 5.7 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.7 2015/06/29 02:44:16 mcalabre Exp $
@


5.6
log
@WCSLIB 5.6
@
text
@d3 1
a3 1
  WCSLIB 5.6 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.5.1.1 2015/05/05 13:21:00 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.6 - C routines that implement the FITS World Coordinate System
@


5.6.1.1
log
@WCSLIB 5.6 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.6 2015/06/14 07:11:24 mcalabre Exp $
@


5.5
log
@WCSLIB 5.5
@
text
@d3 1
a3 1
  WCSLIB 5.5 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.4.1.2 2015/04/23 11:03:11 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.5 - C routines that implement the FITS World Coordinate System
@


5.5.1.1
log
@WCSLIB 5.5 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.5 2015/05/05 13:16:31 mcalabre Exp $
@


5.4
log
@WCSLIB 5.4
@
text
@d3 1
a3 1
  WCSLIB 5.4 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.3.1.1 2015/04/21 02:54:02 mcalabre Exp mcalabre $
d28 3
a30 15
* WCSLIB 5.4 - C routines that implement the FITS World Coordinate System
* (WCS) standard.  Refer to
*
*   "Representations of world coordinates in FITS",
*   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
*
*   "Representations of celestial coordinates in FITS",
*   Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II)
*
*   "Representations of spectral coordinates in FITS",
*   Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
*   2006, A&A, 446, 747 (Paper III)
*
* Refer to the README file provided with WCSLIB for an overview of the
* library.
d36 18
a53 2
* file.  They provide the high-level interface between the FITS file and the
* WCS coordinate transformation routines.
@


5.4.1.1
log
@WCSLIB 5.4 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.4 2015/04/21 14:41:05 mcalabre Exp $
@


5.4.1.2
log
@Boilerplate change to the prologue to ensure that references to the WCS
Papers appear in the doxygen manual.  Also referenced Paper IV.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.4.1.1 2015/04/21 14:44:28 mcalabre Exp mcalabre $
d29 14
a42 2
* (WCS) standard.  Refer to the README file provided with WCSLIB for an
* overview of the library.
d48 2
a49 18
* file.  The information is encoded via keywords defined in
*
=   "Representations of world coordinates in FITS",
=   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
=
=   "Representations of celestial coordinates in FITS",
=   Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (WCS Paper II)
=
=   "Representations of spectral coordinates in FITS",
=   Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
=   2006, A&A, 446, 747 (WCS Paper III)
=
=   "Representations of distortions in FITS world coordinate systems",
=   Calabretta, M.R. et al. (WCS Paper IV, draft dated 2004/04/22),
=   available from http://www.atnf.csiro.au/people/Mark.Calabretta
*
* These routines provide the high-level interface between the FITS file and
* the WCS coordinate transformation routines.
@


5.3
log
@WCSLIB 5.3
@
text
@d3 1
a3 1
  WCSLIB 5.3 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.2.1.1 2015/04/15 12:39:14 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.3 - C routines that implement the FITS World Coordinate System
@


5.3.1.1
log
@WCSLIB 5.3 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.3 2015/04/21 02:50:51 mcalabre Exp $
@


5.2
log
@WCSLIB 5.2
@
text
@d3 1
a3 1
  WCSLIB 5.2 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.1.1.2 2015/04/13 08:28:38 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.2 - C routines that implement the FITS World Coordinate System
@


5.2.1.1
log
@WCSLIB 5.2 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.2 2015/04/15 12:35:07 mcalabre Exp $
@


5.1
log
@WCSLIB 5.1
@
text
@d3 1
a3 1
  WCSLIB 5.1 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 5.0.1.1 2015/04/05 12:28:00 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.1 - C routines that implement the FITS World Coordinate System
d171 3
a173 3
*                          -2: Also remove WCS keyrecords that were rejected,
*                              reporting each one and the reason that it was
*                              rejected.
@


5.1.1.1
log
@WCSLIB 5.1 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.1 2015/04/07 10:56:36 mcalabre Exp $
@


5.1.1.2
log
@Minor amendment of prologue text.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.1.1.1 2015/04/07 11:01:10 mcalabre Exp mcalabre $
d171 3
a173 3
*                          -2: As above, but also remove WCS keyrecords that
*                              were rejected, reporting each one and the
*                              reason that it was rejected.
@


5.0
log
@WCSLIB 5.0
@
text
@d3 1
a3 1
  WCSLIB 5.0 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.25.1.4 2015/04/05 06:38:51 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.0 - C routines that implement the FITS World Coordinate System
@


5.0.1.1
log
@WCSLIB 5.0 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 5.0 2015/04/05 12:24:59 mcalabre Exp $
@


4.25
log
@WCSLIB 4.25
@
text
@d3 2
a4 2
  WCSLIB 4.25 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2014, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 4.24.1.1 2014/09/18 15:28:09 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.25 - C routines that implement the FITS World Coordinate System
d160 3
d292 3
d418 1
a418 1
*      defined in WCS Papers II and III that are not parameterised by axis
d434 5
a438 4
*      - WCSHDR_reject: Reject non-standard keywords (that are not otherwise
*              accepted).  A message will optionally be printed on stderr by
*              default, or the stream set by wcsprintf_set(), as determined by
*              the ctrl argument, and nreject will be incremented.
d442 2
a443 1
*              did not exist in the header.
d445 21
a465 2
*              Useful for testing conformance of a FITS header to the WCS
*              standard.
d488 13
d514 3
a516 3
*      - WCSHDR_DOBSn (wcsbth() only): Allow DOBSn, the column-specific analogue
*              of DATE-OBS.  By an oversight this was never formally defined
*              in the standard.
d907 1
a907 1
*                       Pointer to the array of wcsprm structs; set to 0 on
d1106 1
d1114 11
a1124 7
#define WCSHDR_RADECSYS 0x00000040
#define WCSHDR_VSOURCE  0x00000080
#define WCSHDR_DOBSn    0x00000100
#define WCSHDR_LONGKEY  0x00000200
#define WCSHDR_CNAMn    0x00000400
#define WCSHDR_AUXIMG   0x00000800
#define WCSHDR_ALLIMG   0x00001000
d1126 3
a1128 3
#define WCSHDR_IMGHEAD  0x00010000
#define WCSHDR_BIMGARR  0x00020000
#define WCSHDR_PIXLIST  0x00040000
@


4.25.1.1
log
@WCSLIB 4.25 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.25 2014/12/14 14:29:36 mcalabre Exp $
@


4.25.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2015, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 4.25.1.1 2014/12/14 14:32:45 mcalabre Exp mcalabre $
@


4.25.1.3
log
@Added ctrl == 4 option to wcspih() and wcsbth().  Augmented the prologue
comments for WCSHDR_reject to explain how keyrecords may be non-standard.
Added new flags for the relax argument: WCSHDR_strict, WCSHDR_CD0i_0ja,
WCSHDR_PC0i_0ja, WCSHDR_PV0i_0ma, and WCSHDR_PS0i_0ma.  Changed the flag bits
for WCSHDR_IMGHEAD, WCSHDR_BIMGARR, and WCSHDR_PIXLIST so as not to coincide
with the flag bits for the relax argument.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.25.1.2 2015/01/06 01:01:06 mcalabre Exp mcalabre $
a159 3
*                           4: As above, but also report the accepted WCS
*                              keyrecords, with a summary of the number
*                              accepted as well as rejected.
a288 3
*                           4: As above, but also report the accepted WCS
*                              keyrecords, with a summary of the number
*                              accepted as well as rejected.
d428 4
a431 5
*      - WCSHDR_reject: Reject non-standard keyrecords (that are not otherwise
*              explicitly accepted by one of the flags below).  A message will
*              optionally be printed on stderr by default, or the stream set
*              by wcsprintf_set(), as determined by the ctrl argument, and
*              nreject will be incremented.
d435 1
a435 2
*              did not exist in the header.  It is mainly intended for testing
*              conformance of a FITS header to the WCS standard.
d437 2
a438 21
*              Keyrecords may be non-standard in several ways:
*
*                - The keyword may be syntactically valid but with keyvalue of
*                  incorrect type or invalid syntax, or the keycomment may be
*                  malformed.
*
*                - The keyword may strongly resemble a WCS keyword but not, in
*                  fact, be one because it does not conform to the standard.
*                  For example, "CRPIX01" looks like a CRPIXja keyword, but in
*                  fact the leading zero on the axis number violates the basic
*                  FITS standard.  Likewise, "LONPOLE2" is not a valid
*                  LONPOLEa keyword in the WCS standard, and indeed there is
*                  nothing the parser can sensibly do with it.
*
*                - Use of the keyword may be deprecated by the standard.  Such
*                  will be rejected if not explicitly accepted via one of the
*                  flags below.
*
*      - WCSHDR_strict: As for WCSHDR_reject, but also reject AIPS-convention
*              keywords and all other deprecated usage that is not explicitly
*              accepted.
a460 13
*      - WCSHDR_CD0i_0ja: Accept CD0i_0ja (wcspih()).
*      - WCSHDR_PC0i_0ja: Accept PC0i_0ja (wcspih()).
*      - WCSHDR_PV0i_0ma: Accept PV0i_0ja (wcspih()).
*      - WCSHDR_PS0i_0ma: Accept PS0i_0ja (wcspih()).
*              Allow the numerical index to have a leading zero in doubly-
*              parameterised keywords, for example, PC01_01.  WCS Paper I
*              (Sects 2.1.2 & 2.1.4) explicitly disallows leading zeroes.
*              The FITS 3.0 standard document (Sect. 4.1.2.1) states that the
*              index in singly-parameterised keywords (e.g. CTYPEia) "shall
*              not have leading zeroes", and later in Sect. 8.1 that "leading
*              zeroes must not be used" on PVi_ma and PSi_ma.  However, by an
*              oversight, it is silent on PCi_ja and CDi_ja.
*
d474 3
a476 3
*      - WCSHDR_DOBSn (wcsbth() only): Allow DOBSn, the column-specific
*              analogue of DATE-OBS.  By an oversight this was never formally
*              defined in the standard.
d867 1
a867 1
*                       Pointer to the array of wcsprm structs; set to 0x0 on
a1065 1
#define WCSHDR_strict   0x20000000
d1073 7
a1079 11
#define WCSHDR_CD0i_0ja 0x00000040
#define WCSHDR_PC0i_0ja 0x00000080
#define WCSHDR_PV0i_0ma 0x00000100
#define WCSHDR_PS0i_0ma 0x00000200
#define WCSHDR_RADECSYS 0x00000400
#define WCSHDR_VSOURCE  0x00000800
#define WCSHDR_DOBSn    0x00001000
#define WCSHDR_LONGKEY  0x00002000
#define WCSHDR_CNAMn    0x00004000
#define WCSHDR_AUXIMG   0x00008000
#define WCSHDR_ALLIMG   0x00010000
d1081 3
a1083 3
#define WCSHDR_IMGHEAD  0x00100000
#define WCSHDR_BIMGARR  0x00200000
#define WCSHDR_PIXLIST  0x00400000
@


4.25.1.4
log
@Americanized spelling.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.25.1.3 2015/03/15 08:47:22 mcalabre Exp mcalabre $
d418 1
a418 1
*      defined in WCS Papers II and III that are not parameterized by axis
d493 1
a493 1
*              parameterized keywords, for example, PC01_01.  WCS Paper I
d496 1
a496 1
*              index in singly-parameterized keywords (e.g. CTYPEia) "shall
@


4.24
log
@WCSLIB 4.24
@
text
@d3 1
a3 1
  WCSLIB 4.24 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.23.1.1 2014/05/13 05:53:49 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.24 - C routines that implement the FITS World Coordinate System
@


4.24.1.1
log
@WCSLIB 4.24 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.24 2014/09/18 15:25:00 mcalabre Exp $
@


4.23
log
@WCSLIB 4.23
@
text
@d3 1
a3 1
  WCSLIB 4.23 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.22.1.1 2014/04/12 15:06:32 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.23 - C routines that implement the FITS World Coordinate System
@


4.23.1.1
log
@WCSLIB 4.23 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.23 2014/05/13 05:50:51 mcalabre Exp $
@


4.22
log
@WCSLIB 4.22
@
text
@d3 1
a3 1
  WCSLIB 4.22 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.21.1.1 2014/03/24 05:15:28 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.22 - C routines that implement the FITS World Coordinate System
@


4.22.1.1
log
@WCSLIB 4.22 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.22 2014/04/12 15:03:52 mcalabre Exp $
@


4.21
log
@WCSLIB 4.21
@
text
@d3 1
a3 1
  WCSLIB 4.21 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.20.1.2 2014/03/21 06:32:19 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.21 - C routines that implement the FITS World Coordinate System
@


4.21.1.1
log
@WCSLIB 4.21 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.21 2014/03/24 05:12:27 mcalabre Exp $
@


4.20
log
@WCSLIB 4.20
@
text
@d3 2
a4 2
  WCSLIB 4.20 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2013, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 4.19.1.1 2013/09/29 14:20:38 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.20 - C routines that implement the FITS World Coordinate System
@


4.20.1.1
log
@WCSLIB 4.20 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.20 2013/12/18 05:42:49 mcalabre Exp $
@


4.20.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2014, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 4.20.1.1 2013/12/18 05:46:55 mcalabre Exp mcalabre $
@


4.19
log
@WCSLIB 4.19
@
text
@d3 1
a3 1
  WCSLIB 4.19 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.18.1.1 2013/07/13 10:02:37 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.19 - C routines that implement the FITS World Coordinate System
@


4.19.1.1
log
@WCSLIB 4.19 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.19 2013/09/29 14:17:51 mcalabre Exp $
@


4.18
log
@WCSLIB 4.18
@
text
@d3 1
a3 1
  WCSLIB 4.18 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.17.1.1 2013/01/29 05:32:32 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.18 - C routines that implement the FITS World Coordinate System
@


4.18.1.1
log
@WCSLIB 4.18 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.18 2013/07/13 10:00:04 mcalabre Exp $
@


4.17
log
@WCSLIB 4.17
@
text
@d3 1
a3 1
  WCSLIB 4.17 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.16.1.2 2013/01/29 03:44:31 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.17 - C routines that implement the FITS World Coordinate System
@


4.17.1.1
log
@WCSLIB 4.17 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.17 2013/01/29 05:29:20 cal103 Exp $
@


4.16
log
@WCSLIB 4.16
@
text
@d3 2
a4 2
  WCSLIB 4.16 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2012, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 4.15.1.1 2012/09/26 14:27:51 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.16 - C routines that implement the FITS World Coordinate System
d160 2
a161 1
*                       The report is written to stderr.
d289 2
a290 1
*                       The report is written to stderr.
d429 3
a431 3
*              accepted).  A message will optionally be printed on stderr, as
*              determined by the ctrl argument, and nreject will be
*              incremented.
@


4.16.1.1
log
@WCSLIB 4.16 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.16 2012/11/07 04:42:44 cal103 Exp $
@


4.16.1.2
log
@Diagnostic output from wcsbth() and wcspih() can be redirected by
wcsprintf_set().
@
text
@d4 1
a4 1
  Copyright (C) 1995-2013, Mark Calabretta
d25 1
a25 1
  $Id: wcshdr.h,v 4.16.1.1 2012/11/07 04:45:56 cal103 Exp cal103 $
d160 1
a160 2
*                       The report is written to stderr by default, or the
*                       stream set by wcsprintf_set().
d288 1
a288 2
*                       The report is written to stderr by default, or the
*                       stream set by wcsprintf_set().
d427 3
a429 3
*              accepted).  A message will optionally be printed on stderr by
*              default, or the stream set by wcsprintf_set(), as determined by
*              the ctrl argument, and nreject will be incremented.
@


4.15
log
@WCSLIB 4.15
@
text
@d3 1
a3 1
  WCSLIB 4.15 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.14.1.1 2012/07/13 10:04:44 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.15 - C routines that implement the FITS World Coordinate System
@


4.15.1.1
log
@WCSLIB 4.15 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.15 2012/09/26 14:26:05 cal103 Exp $
@


4.14
log
@WCSLIB 4.14
@
text
@d3 1
a3 1
  WCSLIB 4.14 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcshdr.h,v 4.13.1.2 2012/07/13 03:34:20 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.14 - C routines that implement the FITS World Coordinate System
@


4.14.1.1
log
@WCSLIB 4.14 development branch.
@
text
@d25 1
a25 1
  $Id: wcshdr.h,v 4.14 2012/07/13 10:02:27 cal103 Exp $
@


4.13
log
@WCSLIB 4.13
@
text
@d3 1
a3 1
  WCSLIB 4.13 - an implementation of the FITS WCS standard.
d19 1
a19 1
  along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.
d21 5
a25 11
  Correspondence concerning WCSLIB may be directed to:
    Internet email: mcalabre@@atnf.csiro.au
    Postal address: Dr. Mark Calabretta
                    Australia Telescope National Facility, CSIRO
                    PO Box 76
                    Epping NSW 1710
                    AUSTRALIA

  Author: Mark Calabretta, Australia Telescope National Facility
  http://www.atnf.csiro.au/~mcalabre/index.html
  $Id: wcshdr.h,v 4.12.1.1 2012/02/29 07:59:10 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.13 - C routines that implement the FITS World Coordinate System
@


4.13.1.1
log
@WCSLIB 4.13 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.13 2012/03/14 07:39:30 cal103 Exp $
@


4.13.1.2
log
@Changed contact details.
@
text
@d19 1
a19 1
  along with WCSLIB.  If not, see http://www.gnu.org/licenses.
d21 11
a31 5
  Direct correspondence concerning WCSLIB to mark@@calabretta.id.au

  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
  http://www.atnf.csiro.au/people/Mark.Calabretta
  $Id: wcshdr.h,v 4.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $
@


4.12
log
@WCSLIB 4.12
@
text
@d3 1
a3 1
  WCSLIB 4.12 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcshdr.h,v 4.11.1.1 2012/02/20 23:31:13 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.12 - C routines that implement the FITS World Coordinate System
@


4.12.1.1
log
@WCSLIB 4.12 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.12 2012/02/29 07:57:56 cal103 Exp $
@


4.11
log
@WCSLIB 4.11
@
text
@d3 1
a3 1
  WCSLIB 4.11 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcshdr.h,v 4.10.1.1 2012/02/05 23:42:46 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.11 - C routines that implement the FITS World Coordinate System
@


4.11.1.1
log
@WCSLIB 4.11 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.11 2012/02/20 23:30:02 cal103 Exp $
@


4.10
log
@WCSLIB 4.10
@
text
@d3 1
a3 1
  WCSLIB 4.10 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcshdr.h,v 4.9.1.1 2012/01/24 05:41:45 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.10 - C routines that implement the FITS World Coordinate System
@


4.10.1.1
log
@WCSLIB 4.10 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.10 2012/02/05 23:41:44 cal103 Exp $
@


4.9
log
@WCSLIB 4.9
@
text
@d3 1
a3 1
  WCSLIB 4.9 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcshdr.h,v 4.8.1.2 2012/01/24 05:23:06 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.9 - C routines that implement the FITS World Coordinate System
@


4.9.1.1
log
@WCSLIB 4.9 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.9 2012/01/24 05:40:29 cal103 Exp $
@


4.8
log
@WCSLIB 4.8
@
text
@d3 2
a4 2
  WCSLIB 4.8 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2011, Mark Calabretta
d31 1
a31 1
  $Id: wcshdr.h,v 4.7.1.4 2011/08/10 06:27:02 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.8 - C routines that implement the FITS World Coordinate System
@


4.8.1.1
log
@WCSLIB 4.8 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.8 2011/08/15 08:05:53 cal103 Exp $
@


4.8.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2012, Mark Calabretta
d31 1
a31 1
  $Id: wcshdr.h,v 4.8.1.1 2011/08/15 08:07:06 cal103 Exp cal103 $
@


4.7
log
@WCSLIB 4.7
@
text
@d3 1
a3 1
  WCSLIB 4.7 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcshdr.h,v 4.6.1.2 2011/01/14 06:33:16 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.7 - C routines that implement the FITS World Coordinate System
d147 1
d155 1
d191 1
d193 1
d275 1
d283 1
d313 1
d330 1
d353 1
d355 1
d775 5
d793 1
d826 1
d830 1
d869 1
d937 1
d948 1
a948 1
*             int       Status return value:
d951 11
d1054 1
d1102 9
@


4.7.1.1
log
@WCSLIB 4.7 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.7 2011/02/07 07:03:42 cal103 Exp $
@


4.7.1.2
log
@Added error messaging based on wcserr.  Changes supplied by Michael
Droettboom (STScI) with respect to the released WCSLIB 4.7 sources.
@
text
@a764 5
*                         2: Memory allocation failed.
*                         3: Invalid tabular parameters.
*
* If the return value >= 2, a detailed error message is set in the
* wcs->err struct.  See wcserr.h for error handling instructions.
a930 12
*                         2: Memory allocation failed.
*                         3: Linear transformation matrix is singular.
*                         4: Inconsistent or unrecognized coordinate axis
*                            types.
*                         5: Invalid parameter value.
*                         6: Invalid coordinate transformation parameters.
*                         7: Ill-conditioned coordinate transformation
*                            parameters.
*
* If the return value >= 2, a detailed error message is set in the
* wcs->err struct.  See wcserr.h for error handling instructions.

a1069 7
enum wcshdr_errmsg_enum {
  WCSHDRERR_SUCCESS            = 0, /* Success */
  WCSHDRERR_NULL_POINTER       = 1, /* Null wcsprm pointer passed */
  WCSHDRERR_MEMORY             = 2, /* Memory allocation failed */
  WCSHDRERR_BAD_TABULAR_PARAMS = 3, /* Invalid tabular parameters */
  WCSHDRERR_PARSER             = 4  /* Fatal error returned by Flex parser */
};
@


4.7.1.3
log
@Revised implementation of Michael Droettboom's error messaging system.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.7.1.1 2011/02/07 07:04:22 cal103 Exp cal103 $
a146 1
*
a153 1
*
a188 1
*
a189 1
*
a270 1
*
a277 1
*
a306 1
*
a322 1
*
a344 1
*
a345 1
*
d768 2
a769 2
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
a782 1
*
a814 1
*
a817 1
*
a855 1
*
a922 1
*
d945 3
a947 2
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
d1088 5
a1092 6
  WCSHDRERR_SUCCESS            = 0,	/* Success. */
  WCSHDRERR_NULL_POINTER       = 1,	/* Null wcsprm pointer passed. */
  WCSHDRERR_MEMORY             = 2,	/* Memory allocation failed. */
  WCSHDRERR_BAD_TABULAR_PARAMS = 3,	/* Invalid tabular parameters. */
  WCSHDRERR_PARSER             = 4	/* Fatal error returned by Flex
					   parser. */
@


4.7.1.4
log
@Fixed a long-standing inconsistency in the meaning of status == 3 returned
from wcsbth() and wcstab().
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.7.1.3 2011/08/09 02:43:50 cal103 Exp cal103 $
d779 1
a779 1
*                       wcsprm::err if enabled, see wcserr_enable().
d948 1
a948 1
*             int       Status return value (associated with wcs_errmsg[]):
d961 1
a961 1
*                       wcsprm::err if enabled, see wcserr_enable().
a1053 1
* Use wcs_errmsg[] for status returns from wcshdo().
d1105 2
a1106 2
  WCSHDRERR_BAD_COLUMN         = 3,	/* Invalid column selection. */
  WCSHDRERR_PARSER             = 4,	/* Fatal error returned by Flex
a1107 1
  WCSHDRERR_BAD_TABULAR_PARAMS = 5 	/* Invalid tabular parameters. */
@


4.6
log
@WCSLIB 4.6
@
text
@d3 2
a4 2
  WCSLIB 4.6 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2010, Mark Calabretta
d31 1
a31 1
  $Id: wcshdr.h,v 4.5.1.1 2010/07/16 07:05:31 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.6 - C routines that implement the FITS World Coordinate System
@


4.6.1.1
log
@WCSLIB 4.6 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.6 2010/11/16 06:15:31 cal103 Exp $
@


4.6.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2011, Mark Calabretta
d31 1
a31 1
  $Id: wcshdr.h,v 4.6.1.1 2010/11/16 06:16:19 cal103 Exp cal103 $
@


4.5
log
@WCSLIB 4.5
@
text
@d3 1
a3 1
  WCSLIB 4.5 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcshdr.h,v 4.4.1.3 2010/07/07 07:34:29 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.5 - C routines that implement the FITS World Coordinate System
@


4.5.1.1
log
@WCSLIB 4.5 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.5 2010/07/16 07:01:25 cal103 Exp $
@


4.4
log
@WCSLIB 4.4
@
text
@d3 2
a4 2
  WCSLIB 4.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2009, Mark Calabretta
d31 1
a31 1
  $Id: wcshdr.h,v 4.3.1.3 2009/07/22 05:10:07 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.4 - C routines that implement the FITS World Coordinate System
d653 2
a654 15
*      Likewise, VELREF is subordinate to the formalism of WCS Paper III.  In
*      the AIPS convention VELREF has the following integer values:
*        - 1: LSR kinematic, originally described simply as "LSR" without
*                            distinction between the kinematic and dynamic
*                            definitions.
*        - 2: Barycentric, originally described as "HEL" meaning heliocentric.
*        - 3: Topocentric, originally described as "OBS" meaning geocentric
*                          but widely interpreted as topocentric.
*      AIPS++ extensions to VELREF are also recognized:
*        - 4: LSR dynamic.
*        - 5: Geocentric.
*        - 6: Source rest frame.
*        - 7: Galactocentric.
*      A radio convention velocity is denoted by adding 256 to these,
*      otherwise an optical velocity is indicated.
d660 1
a660 1
*   6: Depending on what flags have been set in its "relax" xargument,
@


4.4.1.1
log
@WCSLIB 4.4 development branch.
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.4 2009/08/06 07:41:33 cal103 Exp $
@


4.4.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2010, Mark Calabretta
d31 1
a31 1
  $Id: wcshdr.h,v 4.4.1.1 2009/08/10 08:52:49 cal103 Exp cal103 $
@


4.4.1.3
log
@Replaced the paragraph on VELREF in note 5 with a reference to spcaips().
@
text
@d31 1
a31 1
  $Id: wcshdr.h,v 4.4.1.2 2010/01/19 03:42:50 cal103 Exp cal103 $
d653 15
a667 2
*      Likewise, VELREF is subordinate to the formalism of WCS Paper III, see
*      spcaips().
d673 1
a673 1
*   6: Depending on what flags have been set in its "relax" argument,
@


4.3
log
@WCSLIB 4.3
@
text
@d3 2
a4 2
    WCSLIB 4.3 - an implementation of the FITS WCS standard.
    Copyright (C) 1995-2007, Mark Calabretta
d6 1
a6 1
    This file is part of WCSLIB.
d8 24
a31 24
    WCSLIB is free software: you can redistribute it and/or modify it under
    the terms of the GNU Lesser General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
    more details.

    You should have received a copy of the GNU Lesser General Public License
    along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.

    Correspondence concerning WCSLIB may be directed to:
       Internet email: mcalabre@@atnf.csiro.au
       Postal address: Dr. Mark Calabretta
                       Australia Telescope National Facility, CSIRO
                       PO Box 76
                       Epping NSW 1710
                       AUSTRALIA

    Author: Mark Calabretta, Australia Telescope National Facility
    http://www.atnf.csiro.au/~mcalabre/index.html
    $Id: wcshdr.h,v 4.2.1.13 2007/12/27 05:15:55 cal103 Exp cal103 $
d34 2
a35 2
*   WCSLIB 4.3 - C routines that implement the FITS World Coordinate System
*   (WCS) standard.  Refer to
d37 2
a38 2
*      "Representations of world coordinates in FITS",
*      Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
d40 2
a41 2
*      "Representations of celestial coordinates in FITS",
*      Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II)
d43 3
a45 3
*      "Representations of spectral coordinates in FITS",
*      Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
*      2006, A&A, 446, 747 (Paper III)
d47 2
a48 2
*   Refer to the README file provided with WCSLIB for an overview of the
*   library.
d51 5
a55 5
*   Summary of wcshdr routines
*   --------------------------
*   Routines in this suite are aimed at extracting WCS information from a FITS
*   file.  They provide the high-level interface between the FITS file and the
*   WCS coordinate transformation routines.
d57 2
a58 2
*   Additionally, function wcshdo() is provided to write out the contents of a
*   wcsprm struct as a FITS header.
d60 1
a60 1
*   Briefly, the anticipated sequence of operations is as follows:
d62 2
a63 2
*      1: Open the FITS file and read the image or binary table header, e.g.
*         using CFITSIO routine fits_hdr2str().
d65 2
a66 2
*      2: Parse the header using wcspih() or wcsbth(); they will automatically
*         interpret -TAB header keywords using wcstab().
d68 5
a72 5
*      3: Allocate memory for, and read -TAB arrays from the binary table
*         extension, e.g. using CFITSIO routine fits_read_wcstab() - refer to
*         the prologue of getwcstab.h.  wcsset() will automatically take
*         control of this allocated memory, in particular causing it to be
*         free'd by wcsfree().
d74 1
a74 1
*      4: Translate non-standard WCS usage using wcsfix(), see wcsfix.h.
d76 4
a79 4
*      5: Initialize wcsprm struct(s) using wcsset() and calculate coordinates
*         using wcsp2s() and/or wcss2p().  Refer to the prologue of wcs.h for
*         a description of these and other high-level WCS coordinate
*         transformation routines.
d81 1
a81 1
*      6: Clean up by freeing memory with wcsvfree().
d83 1
a83 1
*   In detail:
d85 1
a85 1
*   wcspih() is a high-level FITS WCS routine that parses an image header.  It
d89 1
a89 1
*   wcsbth() is the analogue of wcspih() for use with binary tables; it
d94 3
a96 3
*   wcstab() assists in filling in members of the wcsprm struct associated
*   with coordinate lookup tables (-TAB).  These are based on arrays stored in
*   a FITS binary table (BINTABLE) extension that are located by PVi_ma
d99 1
a99 1
*   wcsidx() and wcsbdx() are utility routines that return the index for a
d103 1
a103 1
*   wcsvfree() deallocates memory for an array of wcsprm structs, such as
d106 1
a106 1
*   wcshdo() writes out a wcsprm struct as a FITS header.
d109 47
a155 43
*   FITS WCS parser routine for image headers; wcspih()
*   ---------------------------------------------------
*   wcspih() is a high-level FITS WCS routine that parses an image header,
*   either that of a primary HDU or of an image extension.  All WCS keywords
*   defined in Papers I, II, and III are recognized, and also those used by
*   the AIPS convention and certain other keywords that existed in early
*   drafts of the WCS papers (see note 5 below).
*
*   Given a character array containing a FITS image header, wcspih()
*   identifies and reads all WCS keywords for the primary coordinate
*   representation and up to 26 alternate representations.  It returns this
*   information as an array of wcsprm structs.
*
*   wcspih() invokes wcstab() on each of the wcsprm structs that it returns.
*
*   Given and returned:
*      header   char[]   Character array containing the (entire) FITS image
*                        header from which to idenfify and construct the
*                        coordinate representations, for example, as might be
*                        obtained conveniently via the CFITSIO routine
*                        fits_hdr2str().
*
*                        Each header "keyrecord" (formerly "card image")
*                        consists of exactly 80 7-bit ASCII printing
*                        characters in the range 0x20 to 0x7e (which excludes
*                        NUL, BS, TAB, LF, FF and CR) especially noting that
*                        the keyrecords are NOT null-terminated.
*
*                        For negative values of ctrl (see below), header[] is
*                        modified so that WCS keyrecords processed by wcspih()
*                        are removed from it.
*
*   Given:
*      nkeyrec  int      Number of keyrecords in header[].
*      relax    int      Degree of permissiveness:
*                           0: Recognize only FITS keywords defined by the
*                              published WCS standard.
*                           WCSHDR_all: Admit all recognized informal
*                              extensions of the WCS standard.
*                        Fine-grained control of the degree of permissiveness
*                        is also possible, see note 5 below.
*      ctrl     int      Error reporting and other control options for invalid
*                        WCS and other header keyrecords:
d164 1
a164 1
*                        The report is written to stderr.
d166 2
a167 2
*                        For ctrl < 0, WCS keyrecords processed by wcspih()
*                        are removed from header[]:
d177 103
a279 98
*                              {DATE,MJD}-{OBS,AVG} and OBSGEO-{X,Y,Z}.
*                        If any keyrecords are removed from header[] it will
*                        be null-terminated (NUL not being a legal FITS header
*                        character), otherwise it will contain its original
*                        complement of nkeyrec keyrecords and possibly not be
*                        null-terminated.
*
*   Returned:
*      nreject  int*     Number of WCS keywords rejected for syntax errors,
*                        illegal values, etc.  Keywords not recognized as WCS
*                        keywords are simply ignored (but see also note 5
*                        below).
*      nwcs     int*     Number of coordinate representations found.
*      wcs      struct wcsprm**
*                        Pointer to an array of wcsprm structs containing up
*                        to 27 coordinate representations.
*
*                        Memory for the array is allocated by wcspih() which
*                        also invokes wcsini() for each struct to allocate
*                        memory for internal arrays and initialize their
*                        members to default values (see also note 8 below).
*                        Note that wcsset() is not invoked on these structs.
*
*                        This allocated memory must be freed by the caller,
*                        first by invoking wcsfree() for each struct, and then
*                        by freeing the array itself.  A routine, wcsvfree(),
*                        is provided to do this (see below).
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*                           2: Memory allocation failed.
*
*
*   FITS WCS parser routine for binary table headers; wcsbth()
*   ----------------------------------------------------------
*   wcsbth() is a high-level FITS WCS routine that parses a binary table
*   header.  It handles image array and pixel list WCS keywords which may be
*   present together in one header.
*
*   As an extension of the FITS WCS standard, wcsbth() also recognizes image
*   header keywords in a binary table header.  These may be used to provide
*   default values via an inheritance mechanism discussed below in note 5 (see
*   WCSHDR_AUXIMG and WCSHDR_ALLIMG), or may instead result in wcsprm structs
*   that are not associated with any particular column.  Thus wcsbth() can
*   handle primary image and image extension headers in addition to binary
*   table headers (it ignores NAXIS and does not rely on the presence of the
*   TFIELDS keyword).
*
*   All WCS keywords defined in Papers I, II, and III are recognized, and also
*   those used by the AIPS convention and certain other keywords that existed
*   in early drafts of the WCS papers (see note 5 below).
*
*   wcsbth() sets the colnum or colax[] members of the wcsprm structs that it
*   returns with the column number of an image array or the column numbers
*   associated with each pixel coordinate element in a pixel list.  wcsprm
*   structs that are not associated with any particular column, as may be
*   derived from image header keywords, have colnum == 0.
*
*   Note 6 below discusses the number of wcsprm structs returned by wcsbth(),
*   and the circumstances in which image header keywords cause a struct to be
*   created.  See also note 9 concerning the number of separate images that
*   may be stored in a pixel list.
*
*   The API to wcsbth() is similar to that of wcspih() except for the addition
*   of extra arguments that may be used to restrict its operation.  Like
*   wcspih(), wcsbth() invokes wcstab() on each of the wcsprm structs that it
*   returns.
*
*   Given and returned:
*      header   char[]   Character array containing the (entire) FITS binary
*                        table, primary image, or image extension header from
*                        which to idenfify and construct the coordinate
*                        representations, for example, as might be obtained
*                        conveniently via the CFITSIO routine fits_hdr2str().
*
*                        Each header "keyrecord" (formerly "card image"
*                        consists of exactly 80 7-bit ASCII printing
*                        characters in the range 0x20 to 0x7e (which excludes
*                        NUL, BS, TAB, LF, FF and CR) especially noting that
*                        the keyrecords are NOT null-terminated.
*
*                        For negative values of ctrl (see below), header[] is
*                        modified so that WCS keyrecords processed by wcsbth()
*                        are removed from it.
*
*   Given:
*      nkeyrec  int      Number of keyrecords in header[].
*      relax    int      Degree of permissiveness:
*                           0: Recognize only FITS keywords defined by the
*                              published WCS standard.
*                           WCSHDR_all: Admit all recognized informal
*                              extensions of the WCS standard.
*                        Fine-grained control of the degree of permissiveness
*                        is also possible, see note 5 below.
*      ctrl     int      Error reporting and other control options for invalid
*                        WCS and other header keyrecords:
d288 1
a288 1
*                        The report is written to stderr.
d290 2
a291 2
*                        For ctrl < 0, WCS keyrecords processed by wcsbth()
*                        are removed from header[]:
d301 735
a1035 736
*                              {DATE,MJD}-{OBS,AVG} and OBSGEO-{X,Y,Z}.
*                        If any keyrecords are removed from header[] it will
*                        be null-terminated (NUL not being a legal FITS header
*                        character), otherwise it will contain its original
*                        complement of nkeyrec keyrecords and possibly not be
*                        null-terminated.
*      keysel   int      Given, a vector of flag bits that may be used to
*                        restrict the keyword types considered:
*                          WCSHDR_IMGHEAD: Image header keywords.
*                          WCSHDR_BIMGARR: Binary table image array.
*                          WCSHDR_PIXLIST: Pixel list keywords.
*                        If zero, there is no restriction.
*
*                        Keywords such as EQUIna or RFRQna that are common to
*                        binary table image arrays and pixel lists (including
*                        WCSNna and TWCSna, see note 4 below), are selected by
*                        both WCSHDR_BIMGARR and WCSHDR_PIXLIST.  Thus if
*                        inheritance via WCSHDR_ALLIMG is enabled (see note 5
*                        below) and one of these shared keywords is present,
*                        then WCSHDR_IMGHEAD and WCSHDR_PIXLIST alone may be
*                        sufficient to cause the construction of coordinate
*                        descriptions for binary table image arrays.
*      colsel   int*     Pointer to an array of table column numbers used to
*                        restrict the keywords considered by wcsbth().
*
*                        A null pointer may be specified to indicate that
*                        there is no restriction.  Otherwise, the magnitude of
*                        cols[0] specifies the length of the array:
*                          cols[0] > 0: the columns are included,
*                          cols[0] < 0: the columns are excluded.
*
*                        For the pixel list keywords TPn_ka and TCn_ka (and
*                        TPCn_ka and TCDn_ka if WCSHDR_LONGKEY is enabled), 
*                        it is an error for one column to be selected but not
*                        the other.  This is unlike the situation with invalid
*                        keyrecords, which are simply rejected, because the
*                        error is not intrinsic to the header itself but
*                        arises in the way that it is processed.
*
*   Returned:
*      nreject  int*     Number of WCS keywords rejected for syntax errors,
*                        illegal values, etc.  Keywords not recognized as WCS
*                        keywords are simply ignored (but see also note 5
*                        below).
*      nwcs     int*     Number of coordinate representations found.
*      wcs      struct wcsprm**
*                        Pointer to an array of wcsprm structs containing up
*                        to 27027 coordinate representations (see note 6
*                        below).
*
*                        Memory for the array is allocated by wcsbth() which
*                        also invokes wcsini() for each struct to allocate
*                        memory for internal arrays and initialize their
*                        members to default values (see also note 8 below).
*                        Note that wcsset() is not invoked on these structs.
*
*                        This allocated memory must be freed by the caller,
*                        first by invoking wcsfree() for each struct, and then
*                        by freeing the array itself.  A routine, wcsvfree(),
*                        is provided to do this (see below).
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*                           2: Memory allocation failed.
*                           3: Invalid column selection.
*
*
*   Tabular construction routine; wcstab()
*   --------------------------------------
*   wcstab() assists in filling in the information in the wcsprm struct
*   relating to coordinate lookup tables.
*
*   Tabular coordinates (-TAB) present certain difficulties in that the main
*   components of the lookup table - the multidimensional coordinate array
*   plus an index vector for each dimension - are stored in a FITS binary
*   table (BINTABLE) extension.  Information required to locate these arrays
*   is stored in PVi_ma and PSi_ma keywords in the image header.
*
*   wcstab() parses the PVi_ma and PSi_ma keywords associated with each -TAB
*   axis and allocates memory in the wcsprm struct for the required number of
*   tabprm structs.  It sets as much of the tabprm struct as can be gleaned
*   from the image header, and also sets up an array of wtbarr structs
*   (described in the prologue of wcs.h) to assist in extracting the required
*   arrays from the BINTABLE extension(s).
*
*   It is then up to the user to allocate memory for, and copy arrays from the
*   BINTABLE extension(s) into the tabprm structs.  A CFITSIO routine,
*   fits_read_wcstab(), has been provided for this purpose, see getwcstab.h.
*   wcsset() will automatically take control of this allocated memory, in
*   particular causing it to be free'd by wcsfree(); the user must not attempt
*   to free it after wcsset() has been called.
*
*   Note that wcspih() and wcsbth() automatically invoke wcstab() on each of
*   the wcsprm structs that they return.
*
*   Given and returned:
*      wcs      struct wcsprm*
*                        Coordinate transformation parameters (see below).
*
*                        wcstab() sets ntab, tab, nwtb and wtb, allocating
*                        memory for the tab and wtb arrays.  This allocated
*                        memory will be free'd automatically by wcsfree().
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
*
*   Index alternate coordinate representations; wcsidx()
*   ----------------------------------------------------
*   wcsidx() returns an array of 27 indices for the alternate coordinate
*   representations in the array of wcsprm structs returned by wcspih().  For
*   the array returned by wcsbth() it returns indices for the unattached
*   (colnum == 0) representations derived from image header keywords - use
*   wcsbdx() for those derived from binary table image arrays or pixel lists
*   keywords.
*
*   Given:
*      nwcs     int      Number of coordinate representations in the array.
*      wcs      const struct wcsprm**
*                        Pointer to an array of wcsprm structs returned by
*                        wcspih() or wcsbth().
*
*   Returned:
*      alts     int[27]  Index of each alternate coordinate representation in
*                        the array: alts[0] for the primary, alts[1] for 'A',
*                        etc., set to -1 if not present.
*
*                        For example, if there was no 'P' representation then
*                        alts['P'-'A'+1] would be set to -1.  Otherwise,
*                        the address of its wcsprm struct would be
*                        wcs + alts['P'-'A'+1].
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
*
*   Index alternate coordinate representions; wcsbdx()
*   --------------------------------------------------
*   wcsbdx() returns an array of 999 x 27 indices for the alternate coordinate
*   representions for binary table image arrays xor pixel lists in the array
*   of wcsprm structs returned by wcsbth().  Use wcsidx() for the unattached
*   representations derived from image header keywords.
*
*   Given:
*      nwcs     int      Number of coordinate representations in the array.
*      wcs      const struct wcsprm**
*                        Pointer to an array of wcsprm structs returned by
*                        wcsbth().
*      type     int      Select the type of coordinate representation:
*                          0: binary table image arrays,
*                          1: pixel lists.
*
*   Returned:
*      alts     short[1000][28]
*                        Index of each alternate coordinate represention in
*                        the array: alts[col][0] for the primary, alts[col][1]
*                        for 'A', to alts[col][26] for 'Z', where col is the
*                        1-relative column number, and col == 0 is used for
*                        unattached image headers.  Set to -1 if not present.
*
*                        alts[col][27] counts the number of coordinate
*                        representations of the chosen type for each column.
*
*                        For example, if there was no 'P' represention for
*                        column 13 then alts[13]['P'-'A'+1] would be set
*                        to -1.  Otherwise, the address of its wcsprm struct
*                        would be wcs + alts[13]['P'-'A'+1].
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
*
*   Free the array of wcsprm structs; wcsvfree()
*   --------------------------------------------
*   wcsvfree() frees the memory allocated by wcspih() or wcsbth() for the
*   array of wcsprm structs, first invoking wcsfree() on each of the array
*   members.
*
*   Given and returned:
*      nwcs     int*     Number of coordinate representations found; set to 0
*                        on return.
*      wcs      struct wcsprm**
*                        Pointer to the array of wcsprm structs; set to 0 on
*                        return.
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
*
*   Write out a wcsprm struct as a FITS header; wcshdo()
*   ----------------------------------------------------
*   wcshdo() translates a wcsprm struct into a FITS header.  If the colnum
*   member of the struct is non-zero then a binary table image array header
*   will be produced.  Otherwise, if the colax[] member of the struct is set
*   non-zero then a pixel list header will be produced.  Otherwise, a primary
*   image or image extension header will be produced.
*
*   If the struct was originally constructed from a header, e.g. by wcspih,
*   the output header will almost certainly differ in a number of respects:
*
*     1) The output header only contains WCS-related keywords.  In particular,
*        it does not contain syntactically-required keywords such as SIMPLE,
*        NAXIS, BITPIX, or END.
*
*     2) Deprecated (e.g. CROTAn) or non-standard usage will be translated to
*        standard (this is partially dependent on whether wcsfix() was
*        applied).
*
*     3) Quantities will be converted to the units used internally, basically
*        SI with the addition of degrees.
*
*     4) Floating-point quantities may be given to a different decimal
*        precision.
*
*     5) Elements of the PCi_j matrix will be written if and only if they
*        differ from the unit matrix.  Thus, if the matrix is unity then no
*        elements will be written.
*
*     6) Additional keywords such as WCSAXES, CUNITia, LONPOLEa and LATPOLEa
*        may appear.
*
*     7) The original keycomments will be lost, although wcshdo() tries hard
*        to write meaningful comments.
*
*     8) Keyword order may be changed.
*
*   Keywords can be translated between the image array, binary table, and
*   pixel lists forms by manipulating the colnum or colax[] members of the
*   wcsprm struct.
*
*   Given:
*      relax    int      Degree of permissiveness:
*                           0: Recognize only FITS keywords defined by the
*                              published WCS standard.
*                          -1: Admit all informal extensions of the WCS
*                              standard.
*                        Fine-grained control of the degree of permissiveness
*                        is also possible, see note 10 below.
*
*   Given and returned:
*      wcs      struct wcsprm*
*                        Pointer to a wcsprm struct containing coordinate
*                        transformation parameters.  Will be initialized if
*                        necessary.
*
*   Returned:
*      nkeyrec  int*     Number of FITS header keyrecords returned in the
*                        "header" array.
*      header   char**   Pointer to an array of char holding the header.
*                        Storage for the array is allocated by wcshdo() in
*                        blocks of 2880 bytes (32 x 80-character keyrecords)
*                        and must be free'd by the user to avoid memory leaks.
*
*                        Each keyrecord is 80 characters long and is *NOT*
*                        null-terminated, so the first keyrecord starts at
*                        (*header)[0], the second at (*header)[80], etc.
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
*
*   Notes
*   -----
*    1) wcspih() determines the number of coordinate axes independently for
*       each alternate coordinate representation (denoted by the "a" value in
*       keywords like CTYPEia) from the higher of
*
*         a) NAXIS,
*         b) WCSAXESa,
*         c) The highest axis number in any parameterized WCS keyword.  The
*            keyvalue, as well as the keyword, must be syntactically valid
*            otherwise it will not be considered.
*
*       If none of these keyword types is present, i.e. if the header only
*       contains auxiliary WCS keywords for a particular coordinate
*       representation, then no coordinate description is constructed for it.
*
*       wcsbth() is similar except that it ignores the NAXIS keyword if given
*       an image header to process.
*
*       The number of axes, which is returned as a member of the wcsprm
*       struct, may differ for different coordinate representations of the
*       same image.
*
*    2) wcspih() and wcsbth() enforce correct FITS "keyword = value" syntax
*       with regard to "= " occurring in columns 9 and 10.
*
*       However, they do recognize free-format character (NOST 100-2.0,
*       Sect. 5.2.1), integer (Sect. 5.2.3), and floating-point values
*       (Sect. 5.2.4) for all keywords.
*
*    3) Where CROTAn, CDi_ja, and PCi_ja occur together in one header wcspih()
*       and wcsbth() treat them as described in the prologue to wcs.h.
*
*    4) WCS Paper I mistakenly defined the pixel list form of WCSNAMEa as
*       TWCSna instead of WCSNna; the 'T' is meant to substitute for the axis
*       number in the binary table form of the keyword - note that keywords
*       defined in WCS Papers II and III that are not parameterised by axis
*       number have identical forms for binary tables and pixel lists.
*       Consequently wcsbth() always treats WCSNna and TWCSna as equivalent.
*
*    5) wcspih() and wcsbth() interpret the "relax" argument as a vector of
*       flag bits to provide fine-grained control over what non-standard WCS
*       keywords to accept.  The flag bits are subject to change in future and
*       should be set by using the preprocessor macros defined below for the
*       purpose.
*
*         WCSHDR_none: Don't accept any extensions (not even those in the
*               errata).  Treat non-conformant keywords in the same way as
*               non-WCS keywords in the header, i.e. simply ignore them.
*
*         WCSHDR_reject: Reject non-standard keywords (that are not otherwise
*               accepted).  A message will optionally be printed on stderr, as
*               determined by the ctrl argument, and nreject will be
*               incremented.
*
*               This flag may be used to signal the presence of non-standard
*               keywords, otherwise they are simply passed over as though they
*               did not exist in the header.
*
*               Useful for testing conformance of a FITS header to the WCS
*               standard.
*
*         WCSHDR_all: Accept all extensions recognized by the parser.
*
*         WCSHDR_CROTAia: Accept CROTAia (wcspih),
*                                iCROTna (wcsbth),
*                                TCROTna (wcsbth).
*         WCSHDR_EPOCHa:  Accept EPOCHa.
*         WCSHDR_VELREFa: Accept VELREFa.
*               wcspih() always recognizes the AIPS-convention keywords,
*               CROTAn, EPOCH, and VELREF for the primary representation
*               (a = ' ') but alternates are non-standard.
*
*               wcsbth() accepts EPOCHa and VELREFa only if WCSHDR_AUXIMG is
*               also enabled.
*
*         WCSHDR_CD00i00j: Accept CD00i00j (wcspih).
*         WCSHDR_PC00i00j: Accept PC00i00j (wcspih).
*         WCSHDR_PROJPn:   Accept PROJPn   (wcspih).
*               These appeared in early drafts of WCS Paper I+II (before they
*               were split) and are equivalent to CDi_ja, PCi_ja, and PVi_ma
*               for the primary representation (a = ' ').  PROJPn is
*               equivalent to PVi_ma with m = n <= 9, and is associated
*               exclusively with the latitude axis.
*
*         WCSHDR_RADECSYS: Accept RADECSYS.  This appeared in early drafts of
*               WCS Paper I+II and was subsequently replaced by RADESYSa.
*
*               wcsbth() accepts RADECSYS only if WCSHDR_AUXIMG is also
*               enabled.
*
*         WCSHDR_VSOURCE: Accept VSOURCEa or VSOUna (wcsbth).  This appeared
*               in early drafts of WCS Paper III and was subsequently dropped
*               in favour of ZSOURCEa and ZSOUna.
*
*               wcsbth() accepts VSOURCEa only if WCSHDR_AUXIMG is also
*               enabled.
*
*         WCSHDR_DOBSn (wcsbth only): Allow DOBSn, the column-specific analogue
*               of DATE-OBS.  By an oversight this was never formally defined
*               in the standard.
*
*         WCSHDR_LONGKEY (wcsbth only): Accept long forms of the alternate
*               binary table and pixel list WCS keywords, i.e. with "a" non-
*               blank.  Specifically
*
*                 jCRPXna  TCRPXna   (jCRPXn, jCRPna, TCRPXn, TCRPna, CRPIXja)
*                          TPCn_ka   (        ijPCna,         TPn_ka, PCi_ja)
*                          TCDn_ka   (        ijCDna,         TCn_ka, CDi_ja)
*                 iCDLTna  TCDLTna   (iCDLTn, iCDEna, TCDLTn, TCDEna, CDELTia)
*                 iCUNIna  TCUNIna   (iCUNIn, iCUNna, TCUNIn, TCUNna, CUNITia)
*                 iCTYPna  TCTYPna   (iCTYPn, iCTYna, TCTYPn, TCTYna, CTYPEia)
*                 iCRVLna  TCRVLna   (iCRVLn, iCRVna, TCRVLn, TCRVna, CRVALia)
*                 iPVn_ma  TPVn_ma   (        iVn_ma,         TVn_ma, PVi_ma)
*                 iPSn_ma  TPSn_ma   (        iSn_ma,         TSn_ma, PSi_ma)
*
*               where the primary and standard alternate forms together with
*               the image-header equivalent are shown in parentheses.
*
*               The long form of these keywords could be described as quasi-
*               standard.  TPCn_ka, iPVn_ma, and TPVn_ma appeared by mistake
*               in the examples in WCS Paper II and subsequently these and
*               also TCDn_ka, iPSn_ma and TPSn_ma were legitimized by the
*               errata to the WCS papers.
*
*               Strictly speaking, the other long forms are non-standard and
*               in fact have never appeared in any draft of the WCS papers nor
*               in the errata.  However, as natural extensions of the primary
*               form they are unlikely to be written with any other intention.
*               Thus it should be safe to accept them provided, of course,
*               that the resulting keyword does not exceed the 8-character
*               limit.
*
*               If WCSHDR_CNAMn is enabled then also accept
*
*                 iCNAMna  TCNAMna   (        iCNAna,         TCNAna, CNAMEia)
*                 iCRDEna  TCRDEna   (        iCRDna,         TCRDna, CRDERia)
*                 iCSYEna  TCSYEna   (        iCSYna,         TCSYna, CSYERia)
*
*               Note that CNAMEia, CRDERia, CSYERia, and their variants are
*               not used by WCSLIB but are stored in the wcsprm struct as
*               auxiliary information.
*
*         WCSHDR_CNAMn (wcsbth only): Accept iCNAMn, iCRDEn, iCSYEn, TCNAMn,
*               TCRDEn, and TCSYEn, i.e. with "a" blank.  While non-standard,
*               these are the obvious analogues of iCTYPn, TCTYPn, etc.
*
*         WCSHDR_AUXIMG (wcsbth only): Allow the image-header form of an
*               auxiliary WCS keyword with representation-wide scope to
*               provide a default value for all images.  This default may be
*               overridden by the column-specific form of the keyword.
*
*               For example, a keyword like EQUINOXa would apply to all image
*               arrays in a binary table, or all pixel list columns with
*               alternate representation "a" unless overridden by EQUIna.
*
*               Specifically the keywords are:
*
*                  LATPOLEa   LATPna
*                  LONPOLEa   LONPna
*                  RESTFREQ   RFRQna
*                  RESTFRQa   RFRQna
*                  RESTWAVa   RWAVna
*
*               whose keyvalues are actually used by WCSLIB, and also keywords
*               that provide auxiliary information that is simply stored in
*               the wcsprm struct:
*
*                  EPOCH        -     ... (No column-specific form.)
*                  EPOCHa       -     ... Only if WCSHDR_EPOCHa is set.
*                  EQUINOXa   EQUIna
*                  RADESYSa   RADEna
*                  RADECSYS   RADEna  ... Only if WCSHDR_RADECSYS is set.
*                  SPECSYSa   SPECna
*                  SSYSOBSa   SOBSna
*                  SSYSSRCa   SSRCna
*                  VELOSYSa   VSYSna
*                  VELANGLa   VANGna
*                  VELREF       -     ... (No column-specific form.)
*                  VELREFa      -     ... Only if WCSHDR_VELREFa is set.
*                  VSOURCEa   VSOUna  ... Only if WCSHDR_VSOURCE is set.
*                  WCSNAMEa   WCSNna  ... Or TWCSna (see below).
*                  ZSOURCEa   ZSOUna
*
*                  DATE-AVG   DAVGn
*                  DATE-OBS   DOBSn
*                  MJD-AVG    MJDAn
*                  MJD-OBS    MJDOBn
*                  OBSGEO-X   OBSGXn
*                  OBSGEO-Y   OBSGYn
*                  OBSGEO-Z   OBSGZn
*
*               where the image-header keywords in the left-hand column
*               provide default values for the column specific keywords on
*               the right.
*
*               Keywords in the last group, such as MJD-OBS, apply to all
*               alternate representations, so MJD-OBS would provide a default
*               value for all images in the header.
*
*               This auxiliary inheritance mechanism applies to binary table
*               image arrays and pixel lists alike.  Most of these keywords
*               have no default value, the exceptions being LONPOLEa and
*               LATPOLEa, and also RADESYSa and EQUINOXa which provide
*               defaults for each other.  Thus the only potential difficulty
*               in using WCSHDR_AUXIMG is that of erroneously inheriting one
*               of these four keywords.
*
*               Unlike WCSHDR_ALLIMG, the existence of one (or all) of these
*               auxiliary WCS image header keywords will not by itself cause a
*               wcsprm struct to be created for alternate representation "a".
*               This is because they do not provide sufficient information to
*               create a non-trivial coordinate representation when used in
*               conjunction with the default values of those keywords, such as
*               CTYPEia, that are parameterized by axis number.
*
*         WCSHDR_ALLIMG (wcsbth only): Allow the image-header form of *all*
*               image header WCS keywords to provide a default value for all
*               image arrays in a binary table (n.b. not pixel list).  This
*               default may be overridden by the column-specific form of the
*               keyword.
*
*               For example, a keyword like CRPIXja would apply to all image
*               arrays in a binary table with alternate representation "a"
*               unless overridden by jCRPna.
*
*               Specifically the keywords are those listed above for
*               WCSHDR_AUXIMG plus
*
*                  WCSAXESa   WCAXna
*
*               which defines the coordinate dimensionality, and the following
*               keywords which are parameterized by axis number:
*
*                  CRPIXja    jCRPna
*                  PCi_ja     ijPCna
*                  CDi_ja     ijCDna
*                  CDELTia    iCDEna
*                  CROTAi     iCROTn
*                  CROTAia       -    ... Only if WCSHDR_CROTAia is set.
*                  CUNITia    iCUNna
*                  CTYPEia    iCTYna
*                  CRVALia    iCRVna
*                  PVi_ma     iVn_ma
*                  PSi_ma     iSn_ma
*
*                  CNAMEia    iCNAna
*                  CRDERia    iCRDna
*                  CSYERia    iCSYna
*
*               where the image-header keywords in the left-hand column
*               provide default values for the column specific keywords on
*               the right.
*
*               This full inheritance mechanism only applies to binary table
*               image arrays, not pixel lists, because in the latter case
*               there is no well-defined association between coordinate axis
*               number and column number.
*
*               Note that CNAMEia, CRDERia, CSYERia, and their variants are
*               not used by WCSLIB but are stored in the wcsprm struct as
*               auxiliary information.
*
*               Note especially that at least one wcsprm struct will be
*               returned for each "a" found in one of the image header
*               keywords listed above:
*
*               * If the image header keywords for "a" ARE NOT inherited by a
*                 binary table, then the struct will not be associated with
*                 any particular table column number and it is up to the user
*                 to provide an association.
*
*               * If the image header keywords for "a" ARE inherited by a
*                 binary table image array, then those keywords are considered
*                 to be "exhausted" and do not result in a separate wcsprm
*                 struct.
*
*       For example, to accept CD00i00j and PC00i00j and reject all other
*       extensions, use
*
*         relax = WCSHDR_reject | WCSHDR_CD00i00j | WCSHDR_PC00i00j;
*
*       The parser always treats EPOCH as subordinate to EQUINOXa if both are
*       present, and VSOURCEa is always subordinate to ZSOURCEa.
*
*       Likewise, VELREF is subordinate to the formalism of WCS Paper III.  In
*       the AIPS convention VELREF has the following integer values:
*         1: LSR kinematic, originally described as "LSR" without distinction
*         2: Barycentric,   originally described as "HEL" meaning heliocentric
*         3: Topocentric,   originally described as "OBS" meaning geocentric
*                           but widely interpreted as topocentric
*       AIPS++ extensions to VELREF are also recognized:
*         4: LSR dynamic
*         5: Geocentric
*         6: Source rest frame
*         7: Galactocentric
*       A radio convention velocity is denoted by adding 256 to these,
*       otherwise an optical velocity is indicated.
*
*       Neither wcspih() nor wcsbth() currently recognize the AIPS-convention
*       keywords ALTRPIX or ALTRVAL which effectively define an alternative
*       representation for a spectral axis.
*
*    6) Depending on what flags have been set in its "relax" argument,
*       wcsbth() could return as many as 27027 wcsprm structs:
*
*         * Up to 27 unattached representations derived from image header
*           keywords.
*
*         * Up to 27 structs for each of up to 999 columns containing an image
*           arrays.
*
*         * Up to 27 structs for a pixel list.
*
*       Note that it is considered legitimate for a column to contain an image
*       array and also form part of a pixel list, and in particular that
*       wcsbth() does not check the the TFORM keyword for a pixel list column
*       to check that it is scalar.
*
*       In practice, of course, a realistic binary table header is unlikely to
*       contain more than a handful of images.
*
*       In order for wcsbth() to create a wcsprm struct for a particular
*       coordinate representation, at least one WCS keyword that defines an
*       axis number must be present, either directly or by inheritance if
*       WCSHDR_ALLIMG is set.
*
*       When the image header keywords for an alternate representation are
*       inherited by a binary table image array via WCSHDR_ALLIMG, those
*       keywords are considered to be "exhausted" and do not result in a
*       separate wcsprm struct.  Otherwise they do.
*
*    7) Neither wcspih() nor wcsbth() check for duplicated keywords, in most
*       cases they accept the last encountered.
*
*    8) wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue
*       of wcs.h) to match the size of the pv[] and ps[] arrays in the wcsprm
*       structs to the number in the header.  Consequently there are no unused
*       elements in the pv[] and ps[] arrays, indeed they will often be of
*       zero length.
*
*    9) The FITS WCS standard for pixel lists assumes that a pixel list
*       defines one and only one image, i.e. that each row of the binary table
*       refers to just one event, e.g. the detection of a single photon or
*       neutrino.
*
*       In the absence of a formal mechanism for identifying the columns
*       containing pixel coordinates (as opposed to pixel values or ancillary
*       data recorded at the time the photon or neutrino was detected),
*       Paper I discusses how the WCS keywords themselves may be used to
*       identify them.
*
*       In practice, however, pixel lists have been used to store multiple
*       images.  Besides not specifying how to identify columns, the pixel
*       list convention is also silent on the method to be used to associate
*       table columns with image axes.
*
*       wcsbth() simply collects all WCS keywords for a particular coordinate
*       representation (i.e. the "a" value in TCTYna) into one wcsprm struct.
*       However, these alternates need not be associated with the same table
*       columns and this allows a pixel list to contain up to 27 separate
*       images.  As usual, if one of these representations happened to contain
*       more than two celestial axes, for example, then an error would result
*       when wcsset() is invoked on it.  In this case the "colsel" argument
*       could be used to restrict the columns used to construct the
*       representation so that it only contained one pair of celestial axes.
*
*   10) wcshdo() interprets the "relax" argument as a vector of flag bits to
*       provide fine-grained control over what non-standard WCS keywords to
*       write.  The flag bits are subject to change in future and should be
*       set by using the preprocessor macros defined below for the purpose.
*
*         WCSHDO_none: Don't use any extensions.
*
*         WCSHDO_all: Write all recognized extensions, equivalent to setting
*               each flag bit.
*
*         WCSHDO_safe: Write all extensions that are considered to be safe and
*               recommended.
*
*         WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS
*               for use in binary tables and pixel lists.  WCS Paper III
*               introduced DATE-AVG and DAVGn but by an oversight DOBSn (the
*               obvious analogy) was never formally defined by the standard.
*               The alternative to using DOBSn is to write DATE-OBS which
*               applies to the whole table.  This usage is considered to be
*               safe and is recommended.
*
*         WCSHDO_TPCn_ka: WCS Paper I defined
*
*                 TPn_ka and TCn_ka for pixel lists
*
*               but WCS Paper II uses TPCn_ka in one example and subsequently
*               the errata for the WCS papers legitimized the use of
*
*                 TPCn_ka and TCDn_ka for pixel lists
*
*               provided that the keyword does not exceed eight characters.
*               This usage is considered to be safe and is recommended because
*               of the non-mnemonic terseness of the shorter forms.
*
*         WCSHDO_PVn_ma: WCS Paper I defined
*
*                 iVn_ma and iSn_ma for bintables and
*                 TVn_ma and TSn_ma for pixel lists
*
*               but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and
*               subsequently the errata for the WCS papers legitimized the
*               use of
*
*                 iPVn_ma and iPSn_ma for bintables and
*                 TPVn_ma and TPSn_ma for pixel lists
*
*               provided that the keyword does not exceed eight characters.
*               This usage is considered to be safe and is recommended because
*               of the non-mnemonic terseness of the shorter forms.
*
*         WCSHDO_CRPXna: For historical reasons WCS Paper I defined
*
*                 jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn, for bintables and
*                 TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists
*
*               for use without an alternate version specifier.  However,
*               because of the eight-character keyword constraint, in order to
*               accommodate column numbers greater than 99 WCS Paper I also
*               defined
*
*                 jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and
*                 TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists
*
*               for use with an alternate version specifier (the "a").  Like
*               the PC, CD, PV, and PS keywords there is an obvious tendency
*               to confuse these two forms for column numbers up to 99.  It
*               is very unlikely that any parser would reject keywords in the
*               first set with a non-blank alternate version specifier so this
*               usage is considered to be safe and is recommended.
*
*         WCSHDO_CNAMna: WCS Papers I and III defined
*
*                 iCNAna,  iCRDna,  and iCSYna  for bintables and
*                 TCNAna,  TCRDna,  and TCSYna  for pixel lists
*
*               By analogy with the above the long forms would be
*
*                 iCNAMna, iCRDEna, and iCSYEna for bintables and
*                 TCNAMna, TCRDEna, and TCSYEna for pixel lists
*
*               Note that these keywords provide auxiliary information only,
*               none of them are needed to compute world coordinates.  This
*               usage is potentially unsafe and is not recommended at this
*               time.
*
*         WCSHDO_WCSNna: In light of note 4 above, write WCSNna instead of
*               TWCSna for pixel lists.  While wcsbth() treats WCSNna and
*               TWCSna as equivalent, other parsers may not.  Consequently,
*               this usage is potentially unsafe and is not recommended at
*               this time.
*
*
*   Status return values
*   --------------------
*   Error messages to match the status value returned from each function are
*   encoded in the wcshdr_errmsg character array.
d1059 1
a1059 1
#define WCSHDR_VSOURCEa 0x00000080
a1068 1
#define WCSHDR_BINTAB   0x00080000
d1084 15
a1098 7
int wcspih(char *, int, int, int, int *, int *, struct wcsprm **);
int wcsbth(char *, int, int, int, int, int *, int *, int*, struct wcsprm **);
int wcstab(struct wcsprm *);
int wcsidx(int, struct wcsprm **, int [27]);
int wcsbdx(int, struct wcsprm **, int, short [1000][28]);
int wcsvfree(int *, struct wcsprm **);
int wcshdo(int, struct wcsprm *, int *, char **);
@


4.3.1.1
log
@WCSLIB 4.3 development branch.
@
text
@d3 2
a4 2
    WCSLIB 4.4 - an implementation of the FITS WCS standard.
    Copyright (C) 1995-2008, Mark Calabretta
d31 1
a31 1
    $Id: wcshdr.h,v 4.3 2007/12/27 05:41:36 cal103 Exp cal103 $
d34 1
a34 1
*   WCSLIB 4.4 - C routines that implement the FITS World Coordinate System
@


4.3.1.2
log
@Replaced references to text "above" or "below" with "(see ... above|below)"
so that they can be parsed out of the doxygen markup.
@
text
@d31 1
a31 1
    $Id: wcshdr.h,v 4.3.1.1 2007/12/27 13:23:47 cal103 Exp cal103 $
d51 2
a52 2
*   Summary of the wcshdr routines
*   ------------------------------
d115 1
a115 1
*   drafts of the WCS papers as explained in note 5 (see below).
d149 1
a149 1
*                        is also possible as explained in note 5 (see below).
d183 1
a183 1
*                        keywords are simply ignored.  Refer also note 5 (see
d193 2
a194 3
*                        members to default values.  Refer also to note 8 (see
*                        below).  Note that wcsset() is not invoked on these
*                        structs.
d216 1
a216 1
*   default values via an inheritance mechanism discussed in note 5 (c.f.
d225 1
a225 1
*   in early drafts of the WCS papers as explained in note 5 (see below).
d233 4
a236 4
*   Note 6 (see below) discusses the number of wcsprm structs returned by
*   wcsbth(), and the circumstances in which image header keywords cause a
*   struct to be created.  See also note 9 concerning the number of separate
*   images that may be stored in a pixel list.
d268 1
a268 1
*                        is also possible, as explained in note 5 (see below).
d307 3
a309 4
*                        WCSNna and TWCSna, as explained in note 4 (see
*                        below), are selected by both WCSHDR_BIMGARR and
*                        WCSHDR_PIXLIST.  Thus if inheritance via
*                        WCSHDR_ALLIMG is enabled as discussed in note 5 (see
d334 2
a335 2
*                        keywords are simply ignored, refer also to note 5
*                        (see below).
d339 2
a340 2
*                        to 27027 coordinate representations, refer to note 6
*                        (see below).
d345 2
a346 3
*                        members to default values.  Refer also to note 8 (see
*                        below).  Note that wcsset() is not invoked on these
*                        structs.
d539 1
a539 1
*                        is also possible as explained in note 10 (see below).
d608 1
a608 1
*       should be set by using the preprocessor macros (see below) for the
d935 1
a935 1
*       set by using the preprocessor macros (see below) for the purpose.
d1007 1
a1007 1
*               By analogy with the above, the long forms would be
d1017 2
a1018 2
*         WCSHDO_WCSNna: In light of note 4 (see above), write WCSNna instead
*               of TWCSna for pixel lists.  While wcsbth() treats WCSNna and
@


4.3.1.3
log
@Changes required for generation of the manual using doxextr and doxygen,
including naming of arguments in function prototypes.
@
text
@d3 2
a4 2
  WCSLIB 4.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2009, Mark Calabretta
d6 1
a6 1
  This file is part of WCSLIB.
d8 24
a31 24
  WCSLIB is free software: you can redistribute it and/or modify it under the
  terms of the GNU Lesser General Public License as published by the Free
  Software Foundation, either version 3 of the License, or (at your option)
  any later version.

  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
  more details.

  You should have received a copy of the GNU Lesser General Public License
  along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.

  Correspondence concerning WCSLIB may be directed to:
    Internet email: mcalabre@@atnf.csiro.au
    Postal address: Dr. Mark Calabretta
                    Australia Telescope National Facility, CSIRO
                    PO Box 76
                    Epping NSW 1710
                    AUSTRALIA

  Author: Mark Calabretta, Australia Telescope National Facility
  http://www.atnf.csiro.au/~mcalabre/index.html
  $Id: wcshdr.h,v 4.3.1.2 2008/04/02 06:17:13 cal103 Exp cal103 $
d34 2
a35 2
* WCSLIB 4.4 - C routines that implement the FITS World Coordinate System
* (WCS) standard.  Refer to
d37 2
a38 2
*   "Representations of world coordinates in FITS",
*   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
d40 2
a41 2
*   "Representations of celestial coordinates in FITS",
*   Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II)
d43 3
a45 3
*   "Representations of spectral coordinates in FITS",
*   Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
*   2006, A&A, 446, 747 (Paper III)
d47 2
a48 2
* Refer to the README file provided with WCSLIB for an overview of the
* library.
d51 5
a55 5
* Summary of the wcshdr routines
* ------------------------------
* Routines in this suite are aimed at extracting WCS information from a FITS
* file.  They provide the high-level interface between the FITS file and the
* WCS coordinate transformation routines.
d57 2
a58 2
* Additionally, function wcshdo() is provided to write out the contents of a
* wcsprm struct as a FITS header.
d60 1
a60 1
* Briefly, the anticipated sequence of operations is as follows:
d62 2
a63 2
*   - 1: Open the FITS file and read the image or binary table header, e.g.
*        using CFITSIO routine fits_hdr2str().
d65 2
a66 2
*   - 2: Parse the header using wcspih() or wcsbth(); they will automatically
*        interpret 'TAB' header keywords using wcstab().
d68 5
a72 5
*   - 3: Allocate memory for, and read 'TAB' arrays from the binary table
*        extension, e.g. using CFITSIO routine fits_read_wcstab() - refer to
*        the prologue of getwcstab.h.  wcsset() will automatically take
*        control of this allocated memory, in particular causing it to be
*        free'd by wcsfree().
d74 1
a74 1
*   - 4: Translate non-standard WCS usage using wcsfix(), see wcsfix.h.
d76 4
a79 4
*   - 5: Initialize wcsprm struct(s) using wcsset() and calculate coordinates
*        using wcsp2s() and/or wcss2p().  Refer to the prologue of wcs.h for a
*        description of these and other high-level WCS coordinate
*        transformation routines.
d81 1
a81 1
*   - 6: Clean up by freeing memory with wcsvfree().
d83 1
a83 1
* In detail:
d85 1
a85 1
* - wcspih() is a high-level FITS WCS routine that parses an image header.  It
d89 1
a89 1
* - wcsbth() is the analogue of wcspih() for use with binary tables; it
d94 3
a96 3
* - wcstab() assists in filling in members of the wcsprm struct associated
*   with coordinate lookup tables ('TAB').  These are based on arrays stored
*   in a FITS binary table extension (BINTABLE) that are located by PVi_ma
d99 1
a99 1
* - wcsidx() and wcsbdx() are utility routines that return the index for a
d103 1
a103 1
* - wcsvfree() deallocates memory for an array of wcsprm structs, such as
d106 1
a106 1
* - wcshdo() writes out a wcsprm struct as a FITS header.
d109 43
a151 47
* wcspih() - FITS WCS parser routine for image headers
* ----------------------------------------------------
* wcspih() is a high-level FITS WCS routine that parses an image header,
* either that of a primary HDU or of an image extension.  All WCS keywords
* defined in Papers I, II, and III are recognized, and also those used by the
* AIPS convention and certain other keywords that existed in early drafts of
* the WCS papers as explained in wcsbth() note 5.
*
* Given a character array containing a FITS image header, wcspih() identifies
* and reads all WCS keywords for the primary coordinate representation and up
* to 26 alternate representations.  It returns this information as an array of
* wcsprm structs.
*
* wcspih() invokes wcstab() on each of the wcsprm structs that it returns.
*
* Use wcsbth() in preference to wcspih() for FITS headers of unknown type;
* wcsbth() can parse image headers as well as binary table and pixel list
* headers.
*
* Given and returned:
*   header    char[]    Character array containing the (entire) FITS image
*                       header from which to identify and construct the
*                       coordinate representations, for example, as might be
*                       obtained conveniently via the CFITSIO routine
*                       fits_hdr2str().
*
*                       Each header "keyrecord" (formerly "card image")
*                       consists of exactly 80 7-bit ASCII printing characters
*                       in the range 0x20 to 0x7e (which excludes NUL, BS,
*                       TAB, LF, FF and CR) especially noting that the
*                       keyrecords are NOT null-terminated.
*
*                       For negative values of ctrl (see below), header[] is
*                       modified so that WCS keyrecords processed by wcspih()
*                       are removed from it.
*
* Given:
*   nkeyrec   int       Number of keyrecords in header[].
*   relax     int       Degree of permissiveness:
*                         0: Recognize only FITS keywords defined by the
*                            published WCS standard.
*                         WCSHDR_all: Admit all recognized informal
*                            extensions of the WCS standard.
*                       Fine-grained control of the degree of permissiveness
*                       is also possible as explained in wcsbth() note 5.
*   ctrl      int       Error reporting and other control options for invalid
*                       WCS and other header keyrecords:
d160 1
a160 1
*                       The report is written to stderr.
d162 2
a163 2
*                       For ctrl < 0, WCS keyrecords processed by wcspih()
*                       are removed from header[]:
d173 99
a271 103
*                              '{DATE,MJD}-{OBS,AVG}' and 'OBSGEO-{X,Y,Z}'.
*                       If any keyrecords are removed from header[] it will
*                       be null-terminated (NUL not being a legal FITS header
*                       character), otherwise it will contain its original
*                       complement of nkeyrec keyrecords and possibly not be
*                       null-terminated.
*
* Returned:
*   nreject   int*      Number of WCS keywords rejected for syntax errors,
*                       illegal values, etc.  Keywords not recognized as WCS
*                       keywords are simply ignored.  Refer also to wcsbth()
*                       note 5.
*   nwcs      int*      Number of coordinate representations found.
*   wcs       struct wcsprm**
*                       Pointer to an array of wcsprm structs containing up to
*                       27 coordinate representations.
*
*                       Memory for the array is allocated by wcspih() which
*                       also invokes wcsini() for each struct to allocate
*                       memory for internal arrays and initialize their
*                       members to default values.  Refer also to wcsbth()
*                       note 8.  Note that wcsset() is not invoked on these
*                       structs.
*
*                       This allocated memory must be freed by the user, first
*                       by invoking wcsfree() for each struct, and then by
*                       freeing the array itself.  A routine, wcsvfree(), is
*                       provided to do this (see below).
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                         4: Fatal error returned by Flex parser.
*
* Notes:
*   Refer to wcsbth() notes 1, 2, 3, 5, 7, and 8.
*
*
* wcsbth() - FITS WCS parser routine for binary table and image headers
* ---------------------------------------------------------------------
* wcsbth() is a high-level FITS WCS routine that parses a binary table header.
* It handles image array and pixel list WCS keywords which may be present
* together in one header.
*
* As an extension of the FITS WCS standard, wcsbth() also recognizes image
* header keywords in a binary table header.  These may be used to provide
* default values via an inheritance mechanism discussed in note 5 (c.f.
* WCSHDR_AUXIMG and WCSHDR_ALLIMG), or may instead result in wcsprm structs
* that are not associated with any particular column.  Thus wcsbth() can
* handle primary image and image extension headers in addition to binary table
* headers (it ignores NAXIS and does not rely on the presence of the TFIELDS
* keyword).
*
* All WCS keywords defined in Papers I, II, and III are recognized, and also
* those used by the AIPS convention and certain other keywords that existed in
* early drafts of the WCS papers as explained in note 5 below.
*
* wcsbth() sets the colnum or colax[] members of the wcsprm structs that it
* returns with the column number of an image array or the column numbers
* associated with each pixel coordinate element in a pixel list.  wcsprm
* structs that are not associated with any particular column, as may be
* derived from image header keywords, have colnum == 0.
*
* Note 6 below discusses the number of wcsprm structs returned by wcsbth(),
* and the circumstances in which image header keywords cause a struct to be
* created.  See also note 9 concerning the number of separate images that may
* be stored in a pixel list.
*
* The API to wcsbth() is similar to that of wcspih() except for the addition
* of extra arguments that may be used to restrict its operation.  Like
* wcspih(), wcsbth() invokes wcstab() on each of the wcsprm structs that it
* returns.
*
* Given and returned:
*   header    char[]    Character array containing the (entire) FITS binary
*                       table, primary image, or image extension header from
*                       which to identify and construct the coordinate
*                       representations, for example, as might be obtained
*                       conveniently via the CFITSIO routine fits_hdr2str().
*
*                       Each header "keyrecord" (formerly "card image")
*                       consists of exactly 80 7-bit ASCII printing
*                       characters in the range 0x20 to 0x7e (which excludes
*                       NUL, BS, TAB, LF, FF and CR) especially noting that
*                       the keyrecords are NOT null-terminated.
*
*                       For negative values of ctrl (see below), header[] is
*                       modified so that WCS keyrecords processed by wcsbth()
*                       are removed from it.
*
* Given:
*   nkeyrec   int       Number of keyrecords in header[].
*   relax     int       Degree of permissiveness:
*                         0: Recognize only FITS keywords defined by the
*                            published WCS standard.
*                         WCSHDR_all: Admit all recognized informal
*                            extensions of the WCS standard.
*                       Fine-grained control of the degree of permissiveness
*                       is also possible, as explained in note 5 below.
*   ctrl      int       Error reporting and other control options for invalid
*                       WCS and other header keyrecords:
d280 1
a280 1
*                       The report is written to stderr.
d282 2
a283 2
*                       For ctrl < 0, WCS keyrecords processed by wcsbth()
*                       are removed from header[]:
d293 738
a1030 735
*                              '{DATE,MJD}-{OBS,AVG}' and 'OBSGEO-{X,Y,Z}'.
*                       If any keyrecords are removed from header[] it will
*                       be null-terminated (NUL not being a legal FITS header
*                       character), otherwise it will contain its original
*                       complement of nkeyrec keyrecords and possibly not be
*                       null-terminated.
*   keysel    int       Vector of flag bits that may be used to restrict the
*                       keyword types considered:
*                         WCSHDR_IMGHEAD: Image header keywords.
*                         WCSHDR_BIMGARR: Binary table image array.
*                         WCSHDR_PIXLIST: Pixel list keywords.
*                       If zero, there is no restriction.
*
*                       Keywords such as EQUIna or RFRQna that are common to
*                       binary table image arrays and pixel lists (including
*                       WCSNna and TWCSna, as explained in note 4 below) are
*                       selected by both WCSHDR_BIMGARR and WCSHDR_PIXLIST.
*                       Thus if inheritance via WCSHDR_ALLIMG is enabled as
*                       discussed in note 5 and one of these shared keywords
*                       is present, then WCSHDR_IMGHEAD and WCSHDR_PIXLIST
*                       alone may be sufficient to cause the construction of
*                       coordinate descriptions for binary table image arrays.
*   colsel    int*      Pointer to an array of table column numbers used to
*                       restrict the keywords considered by wcsbth().
*
*                       A null pointer may be specified to indicate that there
*                       is no restriction.  Otherwise, the magnitude of
*                       cols[0] specifies the length of the array:
*                         cols[0] > 0: the columns are included,
*                         cols[0] < 0: the columns are excluded.
*
*                       For the pixel list keywords TPn_ka and TCn_ka (and
*                       TPCn_ka and TCDn_ka if WCSHDR_LONGKEY is enabled), it
*                       is an error for one column to be selected but not the
*                       other.  This is unlike the situation with invalid
*                       keyrecords, which are simply rejected, because the
*                       error is not intrinsic to the header itself but
*                       arises in the way that it is processed.
*
* Returned:
*   nreject   int*      Number of WCS keywords rejected for syntax errors,
*                       illegal values, etc.  Keywords not recognized as WCS
*                       keywords are simply ignored, refer also to note 5
*                       below.
*   nwcs      int*      Number of coordinate representations found.
*   wcs       struct wcsprm**
*                       Pointer to an array of wcsprm structs containing up
*                       to 27027 coordinate representations, refer to note 6
*                       below.
*
*                       Memory for the array is allocated by wcsbth() which
*                       also invokes wcsini() for each struct to allocate
*                       memory for internal arrays and initialize their
*                       members to default values.  Refer also to note 8
*                       below.  Note that wcsset() is not invoked on these
*                       structs.
*
*                       This allocated memory must be freed by the user, first
*                       by invoking wcsfree() for each struct, and then by
*                       freeing the array itself.  A routine, wcsvfree(), is
*                       provided to do this (see below).
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                         3: Invalid column selection.
*                         4: Fatal error returned by Flex parser.
*
* Notes:
*   1: wcspih() determines the number of coordinate axes independently for
*      each alternate coordinate representation (denoted by the "a" value in
*      keywords like CTYPEia) from the higher of
*
*        a: NAXIS,
*        b: WCSAXESa,
*        c: The highest axis number in any parameterized WCS keyword.  The
*           keyvalue, as well as the keyword, must be syntactically valid
*           otherwise it will not be considered.
*
*      If none of these keyword types is present, i.e. if the header only
*      contains auxiliary WCS keywords for a particular coordinate
*      representation, then no coordinate description is constructed for it.
*
*      wcsbth() is similar except that it ignores the NAXIS keyword if given
*      an image header to process.
*
*      The number of axes, which is returned as a member of the wcsprm
*      struct, may differ for different coordinate representations of the
*      same image.
*
*   2: wcspih() and wcsbth() enforce correct FITS "keyword = value" syntax
*      with regard to "= " occurring in columns 9 and 10.
*
*      However, they do recognize free-format character (NOST 100-2.0,
*      Sect. 5.2.1), integer (Sect. 5.2.3), and floating-point values
*      (Sect. 5.2.4) for all keywords.
*
*   3: Where CROTAn, CDi_ja, and PCi_ja occur together in one header wcspih()
*      and wcsbth() treat them as described in the prologue to wcs.h.
*
*   4: WCS Paper I mistakenly defined the pixel list form of WCSNAMEa as
*      TWCSna instead of WCSNna; the 'T' is meant to substitute for the axis
*      number in the binary table form of the keyword - note that keywords
*      defined in WCS Papers II and III that are not parameterised by axis
*      number have identical forms for binary tables and pixel lists.
*      Consequently wcsbth() always treats WCSNna and TWCSna as equivalent.
*
*   5: wcspih() and wcsbth() interpret the "relax" argument as a vector of
*      flag bits to provide fine-grained control over what non-standard WCS
*      keywords to accept.  The flag bits are subject to change in future and
*      should be set by using the preprocessor macros (see below) for the
*      purpose.
*
*      - WCSHDR_none: Don't accept any extensions (not even those in the
*              errata).  Treat non-conformant keywords in the same way as
*              non-WCS keywords in the header, i.e. simply ignore them.
*
*      - WCSHDR_all: Accept all extensions recognized by the parser.
*
*      - WCSHDR_reject: Reject non-standard keywords (that are not otherwise
*              accepted).  A message will optionally be printed on stderr, as
*              determined by the ctrl argument, and nreject will be
*              incremented.
*
*              This flag may be used to signal the presence of non-standard
*              keywords, otherwise they are simply passed over as though they
*              did not exist in the header.
*
*              Useful for testing conformance of a FITS header to the WCS
*              standard.
*
*      - WCSHDR_CROTAia: Accept CROTAia (wcspih()),
*                               iCROTna (wcsbth()),
*                               TCROTna (wcsbth()).
*      - WCSHDR_EPOCHa:  Accept EPOCHa.
*      - WCSHDR_VELREFa: Accept VELREFa.
*              wcspih() always recognizes the AIPS-convention keywords,
*              CROTAn, EPOCH, and VELREF for the primary representation
*              (a = ' ') but alternates are non-standard.
*
*              wcsbth() accepts EPOCHa and VELREFa only if WCSHDR_AUXIMG is
*              also enabled.
*
*      - WCSHDR_CD00i00j: Accept CD00i00j (wcspih()).
*      - WCSHDR_PC00i00j: Accept PC00i00j (wcspih()).
*      - WCSHDR_PROJPn:   Accept PROJPn   (wcspih()).
*              These appeared in early drafts of WCS Paper I+II (before they
*              were split) and are equivalent to CDi_ja, PCi_ja, and PVi_ma
*              for the primary representation (a = ' ').  PROJPn is
*              equivalent to PVi_ma with m = n <= 9, and is associated
*              exclusively with the latitude axis.
*
*      - WCSHDR_RADECSYS: Accept RADECSYS.  This appeared in early drafts of
*              WCS Paper I+II and was subsequently replaced by RADESYSa.
*
*              wcsbth() accepts RADECSYS only if WCSHDR_AUXIMG is also
*              enabled.
*
*      - WCSHDR_VSOURCE: Accept VSOURCEa or VSOUna (wcsbth()).  This appeared
*              in early drafts of WCS Paper III and was subsequently dropped
*              in favour of ZSOURCEa and ZSOUna.
*
*              wcsbth() accepts VSOURCEa only if WCSHDR_AUXIMG is also
*              enabled.
*
*      - WCSHDR_DOBSn (wcsbth() only): Allow DOBSn, the column-specific analogue
*              of DATE-OBS.  By an oversight this was never formally defined
*              in the standard.
*
*      - WCSHDR_LONGKEY (wcsbth() only): Accept long forms of the alternate
*              binary table and pixel list WCS keywords, i.e. with "a" non-
*              blank.  Specifically
*
#                jCRPXna  TCRPXna  :  jCRPXn  jCRPna  TCRPXn  TCRPna  CRPIXja
#                   -     TPCn_ka  :    -     ijPCna    -     TPn_ka  PCi_ja
#                   -     TCDn_ka  :    -     ijCDna    -     TCn_ka  CDi_ja
#                iCDLTna  TCDLTna  :  iCDLTn  iCDEna  TCDLTn  TCDEna  CDELTia
#                iCUNIna  TCUNIna  :  iCUNIn  iCUNna  TCUNIn  TCUNna  CUNITia
#                iCTYPna  TCTYPna  :  iCTYPn  iCTYna  TCTYPn  TCTYna  CTYPEia
#                iCRVLna  TCRVLna  :  iCRVLn  iCRVna  TCRVLn  TCRVna  CRVALia
#                iPVn_ma  TPVn_ma  :    -     iVn_ma    -     TVn_ma  PVi_ma
#                iPSn_ma  TPSn_ma  :    -     iSn_ma    -     TSn_ma  PSi_ma
*
*              where the primary and standard alternate forms together with
*              the image-header equivalent are shown rightwards of the colon.
*
*              The long form of these keywords could be described as quasi-
*              standard.  TPCn_ka, iPVn_ma, and TPVn_ma appeared by mistake
*              in the examples in WCS Paper II and subsequently these and
*              also TCDn_ka, iPSn_ma and TPSn_ma were legitimized by the
*              errata to the WCS papers.
*
*              Strictly speaking, the other long forms are non-standard and
*              in fact have never appeared in any draft of the WCS papers nor
*              in the errata.  However, as natural extensions of the primary
*              form they are unlikely to be written with any other intention.
*              Thus it should be safe to accept them provided, of course,
*              that the resulting keyword does not exceed the 8-character
*              limit.
*
*              If WCSHDR_CNAMn is enabled then also accept
*
#                iCNAMna  TCNAMna  :   ---   iCNAna    ---   TCNAna  CNAMEia
#                iCRDEna  TCRDEna  :   ---   iCRDna    ---   TCRDna  CRDERia
#                iCSYEna  TCSYEna  :   ---   iCSYna    ---   TCSYna  CSYERia
*
*              Note that CNAMEia, CRDERia, CSYERia, and their variants are
*              not used by WCSLIB but are stored in the wcsprm struct as
*              auxiliary information.
*
*      - WCSHDR_CNAMn (wcsbth() only): Accept iCNAMn, iCRDEn, iCSYEn, TCNAMn,
*              TCRDEn, and TCSYEn, i.e. with "a" blank.  While non-standard,
*              these are the obvious analogues of iCTYPn, TCTYPn, etc.
*
*      - WCSHDR_AUXIMG (wcsbth() only): Allow the image-header form of an
*              auxiliary WCS keyword with representation-wide scope to
*              provide a default value for all images.  This default may be
*              overridden by the column-specific form of the keyword.
*
*              For example, a keyword like EQUINOXa would apply to all image
*              arrays in a binary table, or all pixel list columns with
*              alternate representation "a" unless overridden by EQUIna.
*
*              Specifically the keywords are:
*
#                LATPOLEa  for LATPna
#                LONPOLEa  for LONPna
#                RESTFREQ  for RFRQna
#                RESTFRQa  for RFRQna
#                RESTWAVa  for RWAVna
*
*              whose keyvalues are actually used by WCSLIB, and also keywords
*              that provide auxiliary information that is simply stored in
*              the wcsprm struct:
*
#                EPOCH         -       ... (No column-specific form.)
#                EPOCHa        -       ... Only if WCSHDR_EPOCHa is set.
#                EQUINOXa  for EQUIna
#                RADESYSa  for RADEna
#                RADECSYS  for RADEna  ... Only if WCSHDR_RADECSYS is set.
#                SPECSYSa  for SPECna
#                SSYSOBSa  for SOBSna
#                SSYSSRCa  for SSRCna
#                VELOSYSa  for VSYSna
#                VELANGLa  for VANGna
#                VELREF        -       ... (No column-specific form.)
#                VELREFa       -       ... Only if WCSHDR_VELREFa is set.
#                VSOURCEa  for VSOUna  ... Only if WCSHDR_VSOURCE is set.
#                WCSNAMEa  for WCSNna  ... Or TWCSna (see below).
#                ZSOURCEa  for ZSOUna
*
#                DATE-AVG  for DAVGn
#                DATE-OBS  for DOBSn
#                MJD-AVG   for MJDAn
#                MJD-OBS   for MJDOBn
#                OBSGEO-X  for OBSGXn
#                OBSGEO-Y  for OBSGYn
#                OBSGEO-Z  for OBSGZn
*
*              where the image-header keywords on the left provide default
*              values for the column specific keywords on the right.
*
*              Keywords in the last group, such as MJD-OBS, apply to all
*              alternate representations, so MJD-OBS would provide a default
*              value for all images in the header.
*
*              This auxiliary inheritance mechanism applies to binary table
*              image arrays and pixel lists alike.  Most of these keywords
*              have no default value, the exceptions being LONPOLEa and
*              LATPOLEa, and also RADESYSa and EQUINOXa which provide
*              defaults for each other.  Thus the only potential difficulty
*              in using WCSHDR_AUXIMG is that of erroneously inheriting one
*              of these four keywords.
*
*              Unlike WCSHDR_ALLIMG, the existence of one (or all) of these
*              auxiliary WCS image header keywords will not by itself cause a
*              wcsprm struct to be created for alternate representation "a".
*              This is because they do not provide sufficient information to
*              create a non-trivial coordinate representation when used in
*              conjunction with the default values of those keywords, such as
*              CTYPEia, that are parameterized by axis number.
*
*      - WCSHDR_ALLIMG (wcsbth() only): Allow the image-header form of *all*
*              image header WCS keywords to provide a default value for all
*              image arrays in a binary table (n.b. not pixel list).  This
*              default may be overridden by the column-specific form of the
*              keyword.
*
*              For example, a keyword like CRPIXja would apply to all image
*              arrays in a binary table with alternate representation "a"
*              unless overridden by jCRPna.
*
*              Specifically the keywords are those listed above for
*              WCSHDR_AUXIMG plus
*
#                WCSAXESa  for WCAXna
*
*              which defines the coordinate dimensionality, and the following
*              keywords which are parameterized by axis number:
*
#                CRPIXja   for jCRPna
#                PCi_ja    for ijPCna
#                CDi_ja    for ijCDna
#                CDELTia   for iCDEna
#                CROTAi    for iCROTn
#                CROTAia        -      ... Only if WCSHDR_CROTAia is set.
#                CUNITia   for iCUNna
#                CTYPEia   for iCTYna
#                CRVALia   for iCRVna
#                PVi_ma    for iVn_ma
#                PSi_ma    for iSn_ma
*
#                CNAMEia   for iCNAna
#                CRDERia   for iCRDna
#                CSYERia   for iCSYna
*
*              where the image-header keywords on the left provide default
*              values for the column specific keywords on the right.
*
*              This full inheritance mechanism only applies to binary table
*              image arrays, not pixel lists, because in the latter case
*              there is no well-defined association between coordinate axis
*              number and column number.
*
*              Note that CNAMEia, CRDERia, CSYERia, and their variants are
*              not used by WCSLIB but are stored in the wcsprm struct as
*              auxiliary information.
*
*              Note especially that at least one wcsprm struct will be
*              returned for each "a" found in one of the image header
*              keywords listed above:
*
*              - If the image header keywords for "a" ARE NOT inherited by a
*                binary table, then the struct will not be associated with
*                any particular table column number and it is up to the user
*                to provide an association.
*
*              - If the image header keywords for "a" ARE inherited by a
*                binary table image array, then those keywords are considered
*                to be "exhausted" and do not result in a separate wcsprm
*                struct.
*
*      For example, to accept CD00i00j and PC00i00j and reject all other
*      extensions, use
*
=        relax = WCSHDR_reject | WCSHDR_CD00i00j | WCSHDR_PC00i00j;
*
*      The parser always treats EPOCH as subordinate to EQUINOXa if both are
*      present, and VSOURCEa is always subordinate to ZSOURCEa.
*
*      Likewise, VELREF is subordinate to the formalism of WCS Paper III.  In
*      the AIPS convention VELREF has the following integer values:
*        - 1: LSR kinematic, originally described simply as "LSR" without
*                            distinction between the kinematic and dynamic
*                            definitions.
*        - 2: Barycentric, originally described as "HEL" meaning heliocentric.
*        - 3: Topocentric, originally described as "OBS" meaning geocentric
*                          but widely interpreted as topocentric.
*      AIPS++ extensions to VELREF are also recognized:
*        - 4: LSR dynamic.
*        - 5: Geocentric.
*        - 6: Source rest frame.
*        - 7: Galactocentric.
*      A radio convention velocity is denoted by adding 256 to these,
*      otherwise an optical velocity is indicated.
*
*      Neither wcspih() nor wcsbth() currently recognize the AIPS-convention
*      keywords ALTRPIX or ALTRVAL which effectively define an alternative
*      representation for a spectral axis.
*
*   6: Depending on what flags have been set in its "relax" xargument,
*      wcsbth() could return as many as 27027 wcsprm structs:
*
*      - Up to 27 unattached representations derived from image header
*        keywords.
*
*      - Up to 27 structs for each of up to 999 columns containing an image
*        arrays.
*
*      - Up to 27 structs for a pixel list.
*
*      Note that it is considered legitimate for a column to contain an image
*      array and also form part of a pixel list, and in particular that
*      wcsbth() does not check the TFORM keyword for a pixel list column to
*      check that it is scalar.
*
*      In practice, of course, a realistic binary table header is unlikely to
*      contain more than a handful of images.
*
*      In order for wcsbth() to create a wcsprm struct for a particular
*      coordinate representation, at least one WCS keyword that defines an
*      axis number must be present, either directly or by inheritance if
*      WCSHDR_ALLIMG is set.
*
*      When the image header keywords for an alternate representation are
*      inherited by a binary table image array via WCSHDR_ALLIMG, those
*      keywords are considered to be "exhausted" and do not result in a
*      separate wcsprm struct.  Otherwise they do.
*
*   7: Neither wcspih() nor wcsbth() check for duplicated keywords, in most
*      cases they accept the last encountered.
*
*   8: wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue
*      of wcs.h) to match the size of the pv[] and ps[] arrays in the wcsprm
*      structs to the number in the header.  Consequently there are no unused
*      elements in the pv[] and ps[] arrays, indeed they will often be of
*      zero length.
*
*   9: The FITS WCS standard for pixel lists assumes that a pixel list
*      defines one and only one image, i.e. that each row of the binary table
*      refers to just one event, e.g. the detection of a single photon or
*      neutrino.
*
*      In the absence of a formal mechanism for identifying the columns
*      containing pixel coordinates (as opposed to pixel values or ancillary
*      data recorded at the time the photon or neutrino was detected),
*      Paper I discusses how the WCS keywords themselves may be used to
*      identify them.
*
*      In practice, however, pixel lists have been used to store multiple
*      images.  Besides not specifying how to identify columns, the pixel
*      list convention is also silent on the method to be used to associate
*      table columns with image axes.
*
*      wcsbth() simply collects all WCS keywords for a particular coordinate
*      representation (i.e. the "a" value in TCTYna) into one wcsprm struct.
*      However, these alternates need not be associated with the same table
*      columns and this allows a pixel list to contain up to 27 separate
*      images.  As usual, if one of these representations happened to contain
*      more than two celestial axes, for example, then an error would result
*      when wcsset() is invoked on it.  In this case the "colsel" argument
*      could be used to restrict the columns used to construct the
*      representation so that it only contained one pair of celestial axes.
*
*
* wcstab() - Tabular construction routine
* ---------------------------------------
* wcstab() assists in filling in the information in the wcsprm struct relating
* to coordinate lookup tables.
*
* Tabular coordinates ('TAB') present certain difficulties in that the main
* components of the lookup table - the multidimensional coordinate array plus
* an index vector for each dimension - are stored in a FITS binary table
* extension (BINTABLE).  Information required to locate these arrays is stored
* in PVi_ma and PSi_ma keywords in the image header.
*
* wcstab() parses the PVi_ma and PSi_ma keywords associated with each 'TAB'
* axis and allocates memory in the wcsprm struct for the required number of
* tabprm structs.  It sets as much of the tabprm struct as can be gleaned from
* the image header, and also sets up an array of wtbarr structs (described in
* the prologue of wcs.h) to assist in extracting the required arrays from the
* BINTABLE extension(s).
*
* It is then up to the user to allocate memory for, and copy arrays from the
* BINTABLE extension(s) into the tabprm structs.  A CFITSIO routine,
* fits_read_wcstab(), has been provided for this purpose, see getwcstab.h.
* wcsset() will automatically take control of this allocated memory, in
* particular causing it to be free'd by wcsfree(); the user must not attempt
* to free it after wcsset() has been called.
*
* Note that wcspih() and wcsbth() automatically invoke wcstab() on each of the
* wcsprm structs that they return.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters (see below).
*
*                       wcstab() sets ntab, tab, nwtb and wtb, allocating
*                       memory for the tab and wtb arrays.  This allocated
*                       memory will be free'd automatically by wcsfree().
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsidx() - Index alternate coordinate representations
* -----------------------------------------------------
* wcsidx() returns an array of 27 indices for the alternate coordinate
* representations in the array of wcsprm structs returned by wcspih().  For
* the array returned by wcsbth() it returns indices for the unattached
* (colnum == 0) representations derived from image header keywords - use
* wcsbdx() for those derived from binary table image arrays or pixel lists
* keywords.
*
* Given:
*   nwcs      int       Number of coordinate representations in the array.
*   wcs       const struct wcsprm**
*                       Pointer to an array of wcsprm structs returned by
*                       wcspih() or wcsbth().
*
* Returned:
*   alts      int[27]   Index of each alternate coordinate representation in
*                       the array: alts[0] for the primary, alts[1] for 'A',
*                       etc., set to -1 if not present.
*
*                       For example, if there was no 'P' representation then
*
=                         alts['P'-'A'+1] == -1;
*
*                       Otherwise, the address of its wcsprm struct would be
*
=                         wcs + alts['P'-'A'+1];
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsbdx() - Index alternate coordinate representions
* ---------------------------------------------------
* wcsbdx() returns an array of 999 x 27 indices for the alternate coordinate
* representions for binary table image arrays xor pixel lists in the array of
* wcsprm structs returned by wcsbth().  Use wcsidx() for the unattached
* representations derived from image header keywords.
*
* Given:
*   nwcs      int       Number of coordinate representations in the array.
*   wcs       const struct wcsprm**
*                       Pointer to an array of wcsprm structs returned by
*                       wcsbth().
*   type      int       Select the type of coordinate representation:
*                         0: binary table image arrays,
*                         1: pixel lists.
*
* Returned:
*   alts      short[1000][28]
*                       Index of each alternate coordinate represention in the
*                       array: alts[col][0] for the primary, alts[col][1] for
*                       'A', to alts[col][26] for 'Z', where col is the
*                       1-relative column number, and col == 0 is used for
*                       unattached image headers.  Set to -1 if not present.
*
*                       alts[col][27] counts the number of coordinate
*                       representations of the chosen type for each column.
*
*                       For example, if there was no 'P' represention for
*                       column 13 then
*
=                         alts[13]['P'-'A'+1] == -1;
*
*                       Otherwise, the address of its wcsprm struct would be
*
=                         wcs + alts[13]['P'-'A'+1];
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsvfree() - Free the array of wcsprm structs
* ---------------------------------------------
* wcsvfree() frees the memory allocated by wcspih() or wcsbth() for the array
* of wcsprm structs, first invoking wcsfree() on each of the array members.
*
* Given and returned:
*   nwcs      int*      Number of coordinate representations found; set to 0
*                       on return.
*   wcs       struct wcsprm**
*                       Pointer to the array of wcsprm structs; set to 0 on
*                       return.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcshdo() - Write out a wcsprm struct as a FITS header
* -----------------------------------------------------
* wcshdo() translates a wcsprm struct into a FITS header.  If the colnum
* member of the struct is non-zero then a binary table image array header will
* be produced.  Otherwise, if the colax[] member of the struct is set non-zero
* then a pixel list header will be produced.  Otherwise, a primary image or
* image extension header will be produced.
*
* If the struct was originally constructed from a header, e.g. by wcspih(),
* the output header will almost certainly differ in a number of respects:
*
*   - The output header only contains WCS-related keywords.  In particular, it
*     does not contain syntactically-required keywords such as SIMPLE, NAXIS,
*     BITPIX, or END.
*
*   - Deprecated (e.g. CROTAn) or non-standard usage will be translated to
*     standard (this is partially dependent on whether wcsfix() was applied).
*
*   - Quantities will be converted to the units used internally, basically SI
*     with the addition of degrees.
*
*   - Floating-point quantities may be given to a different decimal precision.
*
*   - Elements of the PCi_ja matrix will be written if and only if they differ
*     from the unit matrix.  Thus, if the matrix is unity then no elements
*     will be written.
*
*   - Additional keywords such as WCSAXESa, CUNITia, LONPOLEa and LATPOLEa may
*     appear.
*
*   - The original keycomments will be lost, although wcshdo() tries hard to
*     write meaningful comments.
*
*   - Keyword order may be changed.
*
* Keywords can be translated between the image array, binary table, and pixel
* lists forms by manipulating the colnum or colax[] members of the wcsprm
* struct.
*
* Given:
*   relax     int       Degree of permissiveness:
*                          0: Recognize only FITS keywords defined by the
*                             published WCS standard.
*                         -1: Admit all informal extensions of the WCS
*                             standard.
*                       Fine-grained control of the degree of permissiveness
*                       is also possible as explained in the notes below.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Pointer to a wcsprm struct containing coordinate
*                       transformation parameters.  Will be initialized if
*                       necessary.
*
* Returned:
*   nkeyrec   int*      Number of FITS header keyrecords returned in the
*                       "header" array.
*   header    char**    Pointer to an array of char holding the header.
*                       Storage for the array is allocated by wcshdo() in
*                       blocks of 2880 bytes (32 x 80-character keyrecords)
*                       and must be free'd by the user to avoid memory leaks.
*
*                       Each keyrecord is 80 characters long and is *NOT*
*                       null-terminated, so the first keyrecord starts at
*                       (*header)[0], the second at (*header)[80], etc.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
* Notes:
*   wcshdo() interprets the "relax" argument as a vector of flag bits to
*   provide fine-grained control over what non-standard WCS keywords to write.
*   The flag bits are subject to change in future and should be set by using
*   the preprocessor macros (see below) for the purpose.
*
*   - WCSHDO_none: Don't use any extensions.
*
*   - WCSHDO_all: Write all recognized extensions, equivalent to setting each
*           flag bit.
*
*   - WCSHDO_safe: Write all extensions that are considered to be safe and
*           recommended.
*
*   - WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS for
*           use in binary tables and pixel lists.  WCS Paper III introduced
*           DATE-AVG and DAVGn but by an oversight DOBSn (the obvious analogy)
*           was never formally defined by the standard.  The alternative to
*           using DOBSn is to write DATE-OBS which applies to the whole table.
*           This usage is considered to be safe and is recommended.
*
*   - WCSHDO_TPCn_ka: WCS Paper I defined
*
*           - TPn_ka and TCn_ka for pixel lists
*
*           but WCS Paper II uses TPCn_ka in one example and subsequently the
*           errata for the WCS papers legitimized the use of
*
*           - TPCn_ka and TCDn_ka for pixel lists
*
*           provided that the keyword does not exceed eight characters.  This
*           usage is considered to be safe and is recommended because of the
*           non-mnemonic terseness of the shorter forms.
*
*   - WCSHDO_PVn_ma: WCS Paper I defined
*
*           - iVn_ma and iSn_ma for bintables and
*           - TVn_ma and TSn_ma for pixel lists
*
*           but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and
*           subsequently the errata for the WCS papers legitimized the use of
*
*           - iPVn_ma and iPSn_ma for bintables and
*           - TPVn_ma and TPSn_ma for pixel lists
*
*           provided that the keyword does not exceed eight characters.  This
*           usage is considered to be safe and is recommended because of the
*           non-mnemonic terseness of the shorter forms.
*
*   - WCSHDO_CRPXna: For historical reasons WCS Paper I defined
*
*           - jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn for bintables and
*           - TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists
*
*           for use without an alternate version specifier.  However, because
*           of the eight-character keyword constraint, in order to accommodate
*           column numbers greater than 99 WCS Paper I also defined
*
*           - jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and
*           - TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists
*
*           for use with an alternate version specifier (the "a").  Like the
*           PC, CD, PV, and PS keywords there is an obvious tendency to
*           confuse these two forms for column numbers up to 99.  It is very
*           unlikely that any parser would reject keywords in the first set
*           with a non-blank alternate version specifier so this usage is
*           considered to be safe and is recommended.
*
*   - WCSHDO_CNAMna: WCS Papers I and III defined
*
*           - iCNAna,  iCRDna,  and iCSYna  for bintables and
*           - TCNAna,  TCRDna,  and TCSYna  for pixel lists
*
*           By analogy with the above, the long forms would be
*
*           - iCNAMna, iCRDEna, and iCSYEna for bintables and
*           - TCNAMna, TCRDEna, and TCSYEna for pixel lists
*
*           Note that these keywords provide auxiliary information only, none
*           of them are needed to compute world coordinates.  This usage is
*           potentially unsafe and is not recommended at this time.
*
*   - WCSHDO_WCSNna: In light of wcsbth() note 4, write WCSNna instead of
*           TWCSna for pixel lists.  While wcsbth() treats WCSNna and TWCSna
*           as equivalent, other parsers may not.  Consequently, this usage
*           is potentially unsafe and is not recommended at this time.
*
*
* Global variable: const char *wcshdr_errmsg[] - Status return messages
* ---------------------------------------------------------------------
* Error messages to match the status value returned from each function.
d1054 1
a1054 1
#define WCSHDR_VSOURCE  0x00000080
d1064 1
d1080 7
a1086 15
int wcspih(char *header, int nkeyrec, int relax, int ctrl, int *nreject,
           int *nwcs, struct wcsprm **wcs);

int wcsbth(char *header, int nkeyrec, int relax, int ctrl, int keysel,
           int *colsel, int *nreject, int *nwcs, struct wcsprm **wcs);

int wcstab(struct wcsprm *wcs);

int wcsidx(int nwcs, struct wcsprm **wcs, int alts[27]);

int wcsbdx(int nwcs, struct wcsprm **wcs, int type, short alts[1000][28]);

int wcsvfree(int *nwcs, struct wcsprm **wcs);

int wcshdo(int relax, struct wcsprm *wcs, int *nkeyrec, char **header);
@


4.2
log
@WCSLIB 4.2: changed #include of WCSLIB headers from <...> form to "...".
@
text
@d2 30
a31 29
*
*   WCSLIB 4.2 - an implementation of the FITS WCS standard.
*   Copyright (C) 1995-2005, Mark Calabretta
*
*   WCSLIB is free software; you can redistribute it and/or modify it under
*   the terms of the GNU General Public License as published by the Free
*   Software Foundation; either version 2 of the License, or (at your option)
*   any later version.
*
*   WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
*   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
*   FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
*   details.
*
*   You should have received a copy of the GNU General Public License along
*   with WCSLIB; if not, write to the Free Software Foundation, Inc.,
*   59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
*
*   Correspondence concerning WCSLIB may be directed to:
*      Internet email: mcalabre@@atnf.csiro.au
*      Postal address: Dr. Mark Calabretta
*                      Australia Telescope National Facility, CSIRO
*                      PO Box 76
*                      Epping NSW 1710
*                      AUSTRALIA
*
*   Author: Mark Calabretta, Australia Telescope National Facility
*   http://www.atnf.csiro.au/~mcalabre/index.html
*   $Id: wcshdr.h,v 4.1 2005/08/28 06:17:40 cal103 Exp cal103 $
d34 1
a34 1
*   WCSLIB 4.2 - C routines that implement the FITS World Coordinate System
d38 1
a38 1
*      Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (paper I)
d41 1
a41 1
*      Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (paper II)
d44 2
a45 2
*      Greisen, E.W., Valdes, F.G., Calabretta, M.R., & Allen, S.L. 2005, A&A,
*      (paper III, in preparation)
d47 2
d50 3
a52 2
*   Summary of routines
*   -------------------
d55 4
a58 2
*   WCS coordinate transformation routines.  In brief, anticipated sequence of
*   operations is as follows:
d60 1
a60 2
*      1: Open FITS file and read image header, e.g. using CFITSIO routine
*         fits_hdr2str().
d62 5
a66 2
*      2: Parse the header using wcspih(); this will interpret -TAB header
*         cards using wcstab().
d89 6
a94 1
*   wcstab() helps the user to fill in members of the wcsprm struct associated
d96 2
a97 2
*   a FITS binary table (BINTABLE) extension that are located by PVi_ma cards
*   in the image header.
d99 3
a101 3
*   wcsidx() is a utility routine that returns the index for a specified
*   alternate coordinate descriptor in the array of wcsprm structs returned
*   by wcspih().
d104 1
a104 1
*   returned by wcspih().
d106 1
d108 3
a110 2
*   FITS WCS parser routine; wcspih()
*   ---------------------------------
d115 1
a115 1
*   drafts of the WCS papers (see note 4 below).
d117 4
a120 4
*   Given a character array containing a FITS header, wcspih() identifies and
*   reads all WCS cards for the primary coordinate description and up to 26
*   alternate descriptions.  It returns this information as an array of wcsprm
*   structs.
d125 122
a246 2
*      header   char[]   Character array containing the (entire) FITS header
*                        from which to idenfify and construct the coordinate
d250 5
a254 4
*                        Each header "card" consists of exactly 80 7-bit ASCII
*                        printing characters in the range 0x20 to 0x7e (which
*                        excludes NUL, BS, TAB, LF, FF and CR) especially
*                        noting that the cards are NOT null-terminated.
d256 2
a257 2
*                        For negative values of ctrl (see below), header[]
*                        is modified so that WCS cards processed by wcspih()
d261 1
a261 1
*      ncards   int      Number of cards in header[].
d265 2
a266 2
*                           1: Admit all recognized informal extensions of the
*                              WCS standard.
d268 4
a271 4
*                        is also possible, see note 4 below.
*      ctrl  int         Error reporting and other control options for invalid
*                        WCS and other header cards:
*                           0: Do not report any rejected header cards.
d273 6
a278 6
*                              of WCS cards rejected (nreject).
*                           2: Report each rejected card and the reason why it
*                              was rejected.
*                           3: As above, but also report all non-WCS cards
*                              that were discarded, and the number of
*                              coordinate representations (nwcs) found.
d281 6
a286 5
*                        For ctrl < 0, WCS cards processed by wcspih() are
*                        removed from header[]:
*                          -1: Remove only valid WCS cards whose values were
*                              successfully extracted, nothing is reported.
*                          -2: Also remove WCS cards that were rejected,
d291 4
a294 2
*                        If any cards are removed from header[] it will be
*                        null-terminated (NUL not being a legal FITS header
d296 34
a329 2
*                        complement of ncards cards and possibly not be null-
*                        terminated.
d332 4
a335 3
*      nreject  int*     Number of WCS cards rejected for syntax errors,
*                        illegal values, etc.  Cards not recognized as WCS
*                        cards are simply ignored (but see also note 4 below).
d339 2
a340 1
*                        to 27 coordinate representations.
d342 1
a342 1
*                        Memory for the array is allocated by wcspih() which
d345 2
a346 2
*                        members to default values (see note 6 below).  Note
*                        that wcsset() is not invoked on these structs.
d358 1
d370 1
a370 1
*   is stored in PVi_ma and PSi_ma cards in the image header.
d372 2
a373 2
*   wcstab() parses the PVi_ma and PSi_ma cards associated with each -TAB axis
*   and allocates memory in the wcsprm struct for the required number of
d386 2
a387 2
*   Note that wcspih() automatically invokes wcstab() on each of the wcsprm
*   structs that it returns.
d403 2
a404 2
*   Index alternate coordinate descriptions; wcsidx()
*   -------------------------------------------------
d406 34
a439 1
*   descriptions in the array of wcsprm structs returned by wcspih().
d444 5
a448 2
*                        Pointer to an array of wcsprm structs containing up
*                        to 27 coordinate representations.
d451 14
a464 7
*      alts     int[27]  Index of each alternate coordinate description in the
*                        array: alts[0] for the primary, alts[1] for 'A',
*                        etc., set to -1 if not present.  For example, the
*                        address of the wcsprm struct for the 'P' description
*                        would be wcs + alts['P'-'A'+1].  If the 'P'
*                        description was not present then alts['P'-'A'+1]
*                        would be set to -1.
d474 3
a476 2
*   wcsvfree() frees the memory allocated by wcspih() for the array of wcsprm
*   structs, first invoking wcsfree() on each of the array members.
d491 74
d568 2
a569 1
*       each coordinate representation from the higher of
d573 7
a579 1
*         c) The highest axis number in any parameterized WCS card.
d581 2
a582 2
*       The number of axes, returned in each wcsprm struct, may differ for
*       different coordinate representations of the same image.
d584 3
a586 2
*    2) wcspih() enforces correct FITS "keyword = value" syntax with regard
*       to "= " occurring in columns 9 and 10.
d588 4
a591 1
*       However, it does recognize free-format character (NOST 100-2.0,
d596 23
a618 1
*       treats them as described in the prologue to wcs.h.
d620 3
a622 4
*    4) wcspih() interprets its "relax" argument as a vector of flag bits to
*       provide fine-grained control over what non-standard WCS cards to
*       accept.  The flag bits are subject to change in future and should be
*       set by using the preprocessor macros defined below for the purpose.
d624 2
a625 2
*         WCSHDR_all: Accept all extensions recognized by the parser (the
*               other flag bits are ignored).
d627 1
a627 4
*         WCSHDR_reject: Reject non-standard cards (that are not otherwise
*               accepted) and increment nreject.  This signals the presence of
*               such cards, otherwise they are simply discarded as though they
*               did not exist in the header.
d629 3
a631 1
*         WCSHDR_CROTAia: Accept CROTAia.
d634 1
a634 1
*               The parser always recognizes the AIPS-convention keywords,
d638 203
a840 12
*         WCSHDR_CD00i00j: Accept CD00i00j.
*         WCSHDR_PC00i00j: Accept PC00i00j.
*         WCSHDR_PROJPn:   Accept PROJPn.
*               These appeared in early drafts of the WCS proposal and are
*               equivalent to CDi_ja, PCi_ja, and PVi_ma for the primary
*               representation (a = ' ').  PROJPn is equivalent to PVi_ma with
*               m = n <= 9, and is associated exclusively with the latitude
*               axis.
*
*         WCSHDR_VSOURCEa: Accept VSOURCEa.
*               This appeared in early drafts of the WCS Paper III and was
*               subsequently dropped in favour of ZSOURCEa.
d864 2
a865 2
*       wcspih() does not currently recognize the AIPS-convention keywords
*       ALTRPIX or ALTRVAL which effectively define an alternative
d868 2
a869 2
*    5) wcspih() does not check for duplicated cards, it accepts the last
*       encountered.
d871 151
a1021 4
*    6) wcspih() uses wcsnpv() and wcsnps() (refer to the prologue of wcs.h)
*       to match the size of the pv[] and ps[] arrays in the wcsprm structs to
*       the number in the header.  Consequently there are no unused elements
*       in the pv[] and ps[] arrays, indeed they will often be of zero length.
d1040 33
a1072 9
#define WCSHDR_all      0x001
#define WCSHDR_reject   0x002
#define WCSHDR_CROTAia  0x004
#define WCSHDR_EPOCHa   0x008
#define WCSHDR_VELREFa  0x010
#define WCSHDR_CD00i00j 0x020
#define WCSHDR_PC00i00j 0x040
#define WCSHDR_PROJPn   0x080
#define WCSHDR_VSOURCEa 0x100
d1078 1
d1081 1
d1083 1
d1087 1
a1087 1
};
@


4.2.1.1
log
@WCSLIB 4.2 development branch.
@
text
@d3 1
a3 1
*   WCSLIB 4.3 - an implementation of the FITS WCS standard.
d30 1
a30 1
*   $Id: wcshdr.h,v 4.2 2005/09/22 08:53:12 cal103 Exp cal103 $
d33 1
a33 1
*   WCSLIB 4.3 - C routines that implement the FITS World Coordinate System
@


4.2.1.2
log
@Removed an extraneous ';' following the closing '}' of the 'extern "C" {'
block provided for use in C++.
@
text
@d4 1
a4 1
*   Copyright (C) 1995-2006, Mark Calabretta
d30 1
a30 1
*   $Id: wcshdr.h,v 4.2.1.1 2005/12/05 02:39:43 cal103 Exp cal103 $
d37 1
a37 1
*      Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
d40 1
a40 1
*      Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II)
d43 2
a44 2
*      Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
*      2006, A&A, 446, 747 (Paper III)
d399 1
a399 1
}
@


4.2.1.3
log
@Added wcsbth() with detailed explanation of the way that multiple images in
a pixel list are separated (not yet implemented).  Modified wcspih() so that
basic cards, {DATE,MJD}-{OBS,AVG} and OBSGEO-{X,Y,Z}, are not removed from
the header for negative values of the ctrl argument.
@
text
@d4 1
a4 1
*   Copyright (C) 1995-2007, Mark Calabretta
d30 1
a30 1
*   $Id: wcshdr.h,v 4.2.1.2 2006/08/02 00:14:58 cal103 Exp cal103 $
d54 2
a55 2
*      1: Open the FITS file and read the image or binary table header, e.g.
*         using CFITSIO routine fits_hdr2str().
d57 2
a58 2
*      2: Parse the header using wcspih() or wcsbth(); they will interpret
*         -TAB header cards using wcstab().
a80 3
*   wcsbth() is the analogue of wcspih() for use with binary tables.
*   Currently it only handles pixel lists.
*
d88 1
a88 1
*   by wcspih() or wcsbth().
d91 1
a91 1
*   returned by wcspih() or wcsbth().
d94 2
a95 2
*   FITS WCS parser routine for image headers; wcspih()
*   ---------------------------------------------------
d100 1
a100 1
*   drafts of the WCS papers (see note 5 below).
d102 4
a105 4
*   Given a character array containing a FITS image header, wcspih()
*   identifies and reads all WCS cards for the primary coordinate description
*   and up to 26 alternate descriptions.  It returns this information as an
*   array of wcsprm structs.
d110 4
a113 5
*      header   char[]   Character array containing the (entire) FITS image
*                        header from which to idenfify and construct the
*                        coordinate representations, for example, as might be
*                        obtained conveniently via the CFITSIO routine
*                        fits_hdr2str().
d120 3
a122 3
*                        For negative values of ctrl (see below), header[] is
*                        modified so that WCS cards processed by wcspih() are
*                        removed from it.
d132 1
a132 1
*                        is also possible, see note 5 below.
a148 2
*                              Exceptions: basic cards {DATE,MJD}-{OBS,AVG}
*                              and OBSGEO-{X,Y,Z} are preserved.
d163 1
a163 1
*                        cards are simply ignored (but see also note 5 below).
d172 1
a172 1
*                        members to default values (see note 7 below).  Note
a186 18
*   FITS WCS parser routine for binary table headers; wcsbth()
*   ----------------------------------------------------------
*   wcsbth() is a high-level FITS WCS routine that parses a binary table
*   header; currently only pixel list keywords are handled.  All WCS keywords
*   defined in Papers I, II, and III are recognized, and also those used by
*   the AIPS convention and certain other keywords that existed in early
*   drafts of the WCS papers (see note 5 below).
*
*   The interface to wcsbth() is identical to that of wcspih() except that it
*   expects the 'header' argument to contain a FITS binary table header rather
*   than an image header.  Also, the colax[] member of the wcsprm structs that
*   it returns will be set to contain the column numbers associated with each
*   pixel coordinate element.
*
*   Note 2 below explains how wcsbth() aggregates table columns into one or
*   more images.
*
*
d212 2
a213 2
*   Note that wcspih() and wcsbth() automatically invoke wcstab() on each of
*   the wcsprm structs that they return.
d232 1
a232 2
*   descriptions in the array of wcsprm structs returned by wcspih() or
*   wcsbth().
d257 2
a258 3
*   wcsvfree() frees the memory allocated by wcspih() or wcsbth() for the
*   array of wcsprm structs, first invoking wcsfree() on each of the array
*   members.
d276 1
a276 2
*       each alternate coordinate representation (denoted by the "a" value in
*       keywords like CTYPEia) from the higher of
d280 1
a280 88
*         c) The highest axis number in any parameterized WCS keyword.  The
*            card's keyvalue, as well as the keyword, must be syntactically
*            valid otherwise it will not be considered.
*
*       The number of axes, which is returned as a member of the wcsprm
*       struct, may differ for different coordinate representations of the
*       same image.
*
*    2) Parsing of pixel list headers is considerably more complicated than
*       that of image headers since a pixel list may contain multiple images.
*       Moreover, the pixel list convention does not specify how to identify
*       the columns containing pixel coordinates (as opposed to pixel values
*       or ancillary data), nor how to associate columns with image axes.
*
*       However, the WCS keywords can help at least in part.  Pixel coordinate
*       columns may be identifed simply by the presence of a WCS keyword for
*       that column.  They can also to be "tied" into a single image via WCS
*       keywords and/or keyvalues; specifically via TPn_ka or TCn_ka keywords,
*       or via TCTYna keyvalues as a celestial axis pair.  For example, the
*       presence of TP11_12 in a header identifies columns 11 and 22 as
*       containing pixel coordinates and directly ties them together.  If
*       TP12_22 was also present then the combination of the two TPn_ka
*       keywords would indirectly tie columns 11 and 22.  Therefore, these
*       three columns must form part of a single image.
*
*       Where the header contains a single celestial axis pair, e.g. with
*       TCTYna keyvalues 'RA---SIN' and 'DEC--SIN', then the tie is obvious.
*       If there are multiple celestial axis pairs and they are
*       distinguishable, e.g. with TCTYna keyvalues 'RA---SIN' and 'DEC--SIN'
*       on the one hand and 'GLON-ZEA' and 'GLAT-ZEA' on the other, then the
*       ties are also obvious.  However, if they are indistinguishable, e.g.
*       two pairs of 'RA---ZPN'/'DEC--ZPN' then it may not be so obvious how
*       to pair them.  wcsbth() associates the longitude and latitude columns
*
*         1: firstly by any TPn_ka or TCn_ka keywords that may connect them,
*
*         2: if that fails, then by proximity, i.e. by having consecutive
*            column numbers.
*
*       If an association cannot be deduced as above, then all of the columns
*       are considered to be part of one image, but wcsbth() returns a warning
*       status because wcsset() cannot handle multiple celestial pairs and
*       would return an error status for the resulting wcsprm struct.  The
*       celestial axis pairs would have to be separated (based on a priori
*       knowledge) using wcssub().
*
*       In similar vein, two columns may be "anti-tied" if they have an
*       auxiliary WCS keyword of the same form with the same alternate "a"
*       but with differing keyvalue, i.e.
*
*            DAVGn  EQUIna LATPna LONPna MJDAn  MJDOBn OBSGXn OBSGYn
*            OBSGZn RADEna RFRQna RWAVna SOBSna SPECna SSRCna TWCSna
*            VANGna VSYSna ZSOUna
*
*       These columns cannot form part of a single image because the WCS
*       standard (and the WCSLIB implementation) does not provide for more
*       than one of these keywords per image.  Likewise, the standard does
*       not provide for multiple celestial axis pairs or spectral axes in a
*       single image.  If multiples occur in one pixel list header then the
*       related columns are also anti-tied.
*
*       wcsbth() returns an error status if it finds two columns that are both
*       tied and anti-tied.
*
*       Finally there may be columns that are neither tied nor anti-tied.
*       In order to avoid de facto inheritance of auxiliary keyvalues by
*       association in the wcsprm struct, those columns with an auxiliary WCS
*       keyword are considered to form a one-dimensional image.  The remainder
*       are all collected into a single image.
*
*       These rules are best illustrated by example.  Consider a header
*       containing the following keywords (among others):
*
*         TP1_2, RFRQ1, TWCS1,
*         RFRQ7,
*         TWCS16, TP15_16, CTYP16='RA---SIN', CTYP17='DEC--SIN'
*         CTYP21='RA---SIN', CTYP22='DEC--SIN'
*
*       Separate images are defined by columns [1,2], [7], [15,16,17] and
*       [21,22].  Columns 1 and 2 are tied via TP1_2.  If RFRQ1 and RFRQ7 have
*       differing keyvalues then columns 1 and 7 are anti-tied; it would be an
*       error for TP2_7 also to be present in this header.  Columns 16 and 17
*       are tied via the CTYP16 and CTYP17 keyvalues and in turn column 15 is
*       tied them via TP15_16.  It would also be an error for column 1 to be
*       tied to either column 15, 16, or 17 unless TWCS1 and TWCS16 had the
*       same keyvalue.  The celestial axes in columns 21 and 22 are considered
*       to be paired by proximity and form a separate image because the others
*       all have an auxiliary keyword.
d282 2
a283 2
*    3) wcspih() and wcsbth() enforce correct FITS "keyword = value" syntax
*       with regard to "= " occurring in columns 9 and 10.
d285 4
a288 1
*       However, they do recognize free-format character (NOST 100-2.0,
d292 2
a293 2
*    4) Where CROTAn, CDi_ja, and PCi_ja occur together in one header wcspih()
*       and wcsbth() treat them as described in the prologue to wcs.h.
d295 4
a298 5
*    5) wcspih() and wcsbth() interpret the "relax" argument as a vector of
*       flag bits to provide fine-grained control over what non-standard WCS
*       cards to accept.  The flag bits are subject to change in future and
*       should be set by using the preprocessor macros defined below for the
*       purpose.
d308 1
a308 1
*         WCSHDR_CROTAia: Accept CROTAia (wcspih) or TCROTna (wcsbth).
d311 1
a311 1
*               wcspih() always recognizes the AIPS-convention keywords,
d315 3
a317 6
*               wcsbth() accepts EPOCHa and VELREFa only if WCSHDR_TSCOPE is
*               also enabled.
*
*         WCSHDR_CD00i00j: Accept CD00i00j (wcspih).
*         WCSHDR_PC00i00j: Accept PC00i00j (wcspih).
*         WCSHDR_PROJPn:   Accept PROJPn (wcspih).
d324 3
a326 69
*         WCSHDR_VSOURCE: Accept VSOURCEa (wcspih) or VSOUna (wcsbth).
*               This appeared in early drafts of WCS Paper III and was
*               subsequently dropped in favour of ZSOURCEa and ZSOUna.
*
*         WCSHDR_DOBS (wcsbth only): Allow DOBSn, the column-specific analogue
*               of DATE-OBS.  By an oversight this was never formally defined
*               in the standard.
*
*         WCSHDR_LONGKEY (wcsbth only): Accept long forms of the alternate
*               pixel list WCS keywords.  Specifically
*
*                  TCTYPna   (TCTYPn, TCTYna, CTYPEia)
*                  TCUNIna   (TCUNIn, TCUNna, CUNITia)
*                  TCRVLna   (TCRVLn, TCRVna, CRVALia)
*                  TCDLTna   (TCDLTn, TCDLna, CDELTia)
*                  TCRPXna   (TCRPXn, TCRPna, CRPIXja)
*                  TPCn_ka   (TPCn_k, TPn_ka, PCi_ja)
*                  TCDn_ka   (TCDn_k, TCn_ka, CDi_ja)
*                  TPVn_ma   (TPVn_m, TVn_ma, PVi_ma)
*                  TPSn_ma   (TPSn_m, TSn_ma, PSi_ma)
*                  TWCSNna   (TWCSNn, TWCSna, WCSNAMEa)
*                  TCRDEna   (TCRDEn, TCRDna, CRDERia)
*                  TCSYEna   (TCSYEn, TCSYna, CSYERia)
*
*               where the primary and standard alternate forms together with
*               the image-header equivalent are shown in parentheses.  These
*               long forms are non-standard and in fact have never appeared
*               in any draft of the WCS papers.  However, as natural
*               extensions of the primary form they are acceptable provided
*               that the resulting keyword does not exceed the 8-character
*               limit.
*
*         WCSHDR_TSCOPE (wcsbth only): Allow the image-header form of an
*               auxiliary WCS keyword with representation-wide scope to
*               provide a default value for all images that may be overridden
*               by the column-specific form of the keyword.  For example, a
*               keyword like EQUINOXa would apply to all pixel list columns
*               with primary or alternate representation "a".  Specifically
*               these are
*
*                  DATE-AVG   DAVGn
*                  DATE-OBS   DOBSn    ... Only if WCSHDR_DOBS is set.
*                  EPOCHa       -      ... No column-specific form.
*                  EQUINOXa   EQUIna
*                  LATPOLEa   LATPna
*                  LONPOLEa   LONPna
*                  MJD-AVG    MJDAn
*                  MJD-OBS    MJDOBn
*                  OBSGEO-X   OBSGXn
*                  OBSGEO-Y   OBSGYn
*                  OBSGEO-Z   OBSGZn
*                  RADECSYS   RADEna
*                  RADESYSa   RADEna
*                  RESTFREQ   RFRQna
*                  RESTFRQa   RFRQna
*                  RESTWAVa   RWAVna
*                  SPECSYSa   SPECna
*                  SSYSOBSa   SOBSna
*                  SSYSSRCa   SSRCna
*                  VELOSYSa   VSYSna
*                  VELANGLa   VANGna
*                  VELREFa      -     ... No column-specific form.
*                  VSOURCEa   VSOUna  ... Only if WCSHDR_VSOURCE is set.
*                  WCSNAMEa   TWCSna
*                  ZSOURCEa   ZSOUna
*
*               A number of these keywords, such as MJDOBn, apply to all
*               alternate representations, so MJD-OBS would provide a default
*               value for all images in the header.
d350 2
a351 2
*       Neither wcspih() nor wcsbth() currently recognize the AIPS-convention
*       keywords ALTRPIX or ALTRVAL which effectively define an alternative
d354 2
a355 2
*    6) Neither wcspih() nor wcsbth() check for duplicated cards, they accept
*       the last encountered.
d357 4
a360 5
*    7) wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue
*       of wcs.h) to match the size of the pv[] and ps[] arrays in the wcsprm
*       structs to the number in the header.  Consequently there are no unused
*       elements in the pv[] and ps[] arrays, indeed they will often be of
*       zero length.
a387 3
#define WCSHDR_DOBS     0x200
#define WCSHDR_LONGKEY  0x400
#define WCSHDR_TSCOPE   0x800
a392 1
int wcsbth(char *, int, int, int, int *, int *, struct wcsprm **);
@


4.2.1.4
log
@Added documentation and prototype for wcshdo().
@
text
@d30 1
a30 1
*   $Id: wcshdr.h,v 4.2.1.3 2007/07/12 00:24:11 cal103 Exp cal103 $
d51 2
a52 6
*   WCS coordinate transformation routines.
*
*   Additionally, function wcshdo() is provided to write out the contents of a
*   wcsprm struct as FITS header cards.
*
*   In brief, the anticipated sequence of operations is as follows:
a95 2
*   wcshdo() writes out a wcsprm struct as FITS header cards.
*
a298 65
*   Write out a wcsprm struct as FITS header cards; wcshdo()
*   --------------------------------------------------------
*   wcshdo() translates a wcsprm struct into FITS header cards.  If the colnum
*   member of the struct is non-zero then binary table image array cards will
*   be produced.  Otherwise, if the colax[] member of the struct is set non-
*   zero then pixel list cards will be produced.  Otherwise, primary image or
*   image extension header cards will be produced.
*
*   If the struct was originally constructed from a header, e.g. by wcspih,
*   the output cards will almost certainly differ in a number of respects:
*
*     1) The output header only contains WCS-related cards.  In particular, it
*        does not contain syntactically-required cards such as SIMPLE, NAXIS,
*        BITPIX, or END.
*
*     2) Deprecated (e.g. CROTAn) or non-standard usage will be translated to
*        standard (this is partially dependent on whether wcsfix() was
*        applied).
*
*     3) Quantities will be converted to the units used internally, basically
*        SI with the addition of degrees.
*
*     4) Floating-point quantities may be given to a different decimal
*        precision.
*
*     5) Elements of the PCi_j matrix will be written if and only if they
*        differ from the unit matrix.  Thus, if the matrix is unity then no
*        elements will be written.
*
*     6) Additional keywords such as WCSAXES, CUNITia, LONPOLEa and LATPOLEa
*        may appear.
*
*     7) The original inline comments will be lost, although wcshdo() does try
*        to write meaningful comments.
*
*     8) Card order may be changed.
*
*   Cards can be translated between the image array, binary table, and pixel
*   lists forms by manipulating the colnum or colax[] members of the wcsprm
*   struct.
*
*   Given and returned:
*      wcs      struct wcsprm*
*                        Pointer to a wcsprm struct containing coordinate
*                        transformation parameters.  Will be initialized if
*                        necessary.
*
*   Returned:
*      ncards   int*     Number of FITS header cards returned in the 'header'
*                        array.
*      header   char**   Pointer to an array of char holding the header cards.
*                        Storage for the array is allocated by wcshdo() in
*                        blocks of 2880 bytes (32 x 80-character cards) and
*                        must be free'd by the user to avoid memory leaks.
*
*                        Each card is 80 characters long and is *NOT* null-
*                        terminated, so the first card starts at (*header)[0],
*                        the second at (*header)[80], etc.
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
*
a581 1
int wcshdo(struct wcsprm *, int *, char **);
@


4.2.1.5
log
@Added 'relax' to the argument list for wcshdo().
@
text
@d30 1
a30 1
*   $Id: wcshdr.h,v 4.2.1.4 2007/07/27 08:47:26 cal103 Exp cal103 $
a345 9
*   Given:
*      relax    int      Degree of permissiveness:
*                           0: Recognize only FITS keywords defined by the
*                              published WCS standard.
*                          -1: Admit all informal extensions of the WCS
*                              standard.
*                        Fine-grained control of the degree of permissiveness
*                        is also possible, see note 5 below.
*
a482 3
*         WCSHDR_none: Don't accept any extensions, treat non-conformant cards
*               as though they did not exist in the header.
*
a572 1
*        WCSAXESa?
a614 90
*    8) wcshdo() interprets the "relax" argument as a vector of flag bits to
*       provide fine-grained control over what non-standard WCS cards to
*       write.  The flag bits are subject to change in future and should be
*       set by using the preprocessor macros defined below for the purpose.
*
*         WCSHDO_none: Don't use any extensions.
*
*         WCSHDO_all: Write all recognized extensions, equivalent to setting
*               each flag bit.
*
*         WCSHDO_safe: Write all extensions that are considered to be safe and
*               recommended.
*
*         WCSHDO_DOBS: Write DOBSn, the column-specific analogue of DATE-OBS
*               for use in binary tables and pixel lists.  WCS Paper III
*               introduced DATE-AVG and DAVGn but by an oversight DOBSn (the
*               obvious analogy) was never formally defined by the standard. 
*               The alternative to using DOBSn is to write DATE-OBS which
*               applies to the whole table.  This usage is considered to be
*               safe and is recommended.
*
*         WCSHDO_TPC: Paper I defined
*
*                 TPn_ka and TCn_ka for pixel lists
*
*               but Paper II uses TPCn_ka in one example and subsequently the
*               errata for the WCS papers legitimized the use of
*
*                 TPCn_ka and TCDn_ka for pixel lists
*
*               provided that the keyword does not exceed eight characters.
*               This usage is considered to be safe and is recommended because
*               of the non-mnemonic terseness of the shorter forms.
*
*         WCSHDO_PV: Paper I defined
*
*                 iVn_ma and iSn_ma for bintables and
*                 TVn_ma and TSn_ma for pixel lists
*
*               but Paper II uses iPVn_ma and TPVn_ma in the examples and
*               subsequently the errata for the WCS papers legitimized the
*               use of
*
*                 iPVn_ma and iPSn_ma for bintables and
*                 TPVn_ma and TPSn_ma for pixel lists
*
*               provided that the keyword does not exceed eight characters.
*               This usage is considered to be safe and is recommended because
*               of the non-mnemonic terseness of the shorter forms.
*
*         WCSHDO_CRPX: For historical reasons Paper I defined
*
*                 jCRPXn, iCDLTn, iCRVLn, iCUNIn, and iCTYPn for bintables and
*                 TCRPXn, TCDLTn, TCRVLn, TCUNIn, and TCTYPn for pixel lists
*
*               for use without an alternate version specifier.  However,
*               subject to the eight-character keyword constraint, in order to
*               accommodate column numbers greater than 99 it also defined
*
*                 jCRPna, iCDEna, iCRVna, iCUNna, and iCTYna for bintables and
*                 TCRPna, TCDEna, TCRVna, TCUNna, and TCTYna for pixel lists
*
*               for use with an alternate version specifier (the 'a').  Like
*               the PC, CD, PV, and PS keywords there is an obvious tendency
*               to confuse these two forms for column numbers up to 99.  It
*               is very unlikely that a parser would reject keywords in the
*               first set with a non-blank alternate version specifier so this
*               usage is considered to be safe and is recommended.
*
*         WCSHDO_CNAM: Papers I and III defined
*
*                 iCNAna,  iCRDna,  and iCSYna  for bintables and
*                 TCNAna,  TCRDna,  and TCSYna  for pixel lists
*
*               By analogy with the above the long forms would be
*
*                 iCNAMna, iCRDEna, and iCSYEna for bintables and
*                 TCNAMna, TCRDEna, and TCSYEna for pixel lists
*
*               This usage is potentially unsafe and is not recommended at
*               this time.
*
*         WCSHDO_WCSN: Paper I mistakenly defined the pixel list form of
*               WCSNAMEa as TWCSna instead of WCSNna; the 'T' is meant to
*               substitute for the axis number in the binary table form of the
*               keyword - note that keywords defined in Papers II and III that
*               are not parameterised by axis number have identical forms for
*               binary tables and pixel lists.  This usage is potentially
*               unsafe and is not recommended at this time.
*
a631 1
#define WCSHDR_none     0x000
a644 11
#define WCSHDO_none 0x00
#define WCSHDO_all  0xFF
#define WCSHDO_safe 0x0F
#define WCSHDO_DOBS 0x01
#define WCSHDO_TPC  0x02
#define WCSHDO_PV   0x04
#define WCSHDO_CRPX 0x08
#define WCSHDO_CNAM 0x10
#define WCSHDO_WCSN 0x20


d653 1
a653 1
int wcshdo(int, struct wcsprm *, int *, char **);
@


4.2.1.6
log
@Added wcsbdx().  Made the names of the WCSHDO_* relaxation macros more
specific to their association with binary table image arrays and pixel lists.
@
text
@d30 1
a30 1
*   $Id: wcshdr.h,v 4.2.1.5 2007/08/01 08:21:23 cal103 Exp cal103 $
d93 3
a95 3
*   wcsidx() and wcsbdx() are utility routines that return the index for a
*   specified alternate coordinate descriptor in the array of wcsprm structs
*   returned by wcspih() or wcsbth().
d262 2
a263 5
*   representations in the array of wcsprm structs returned by wcspih().  For
*   the array returned by wcsbth() it returns indices for the unattached
*   (colnum == 0) representations derived from image header keywords - use
*   wcsbdx() for those derived from binary table image arrays or pixel lists
*   keywords.
a285 27
*   Index alternate coordinate representions; wcsbdx()
*   -------------------------------------------------
*   wcsbdx() returns an array of 999 x 27 indices for the alternate coordinate
*   representions for binary table image arrays xor pixel lists in the array
*   of wcsprm structs returned by wcsbth().  Use wcsidx() for the unattached
*   representations derived from image header keywords.
*
*   Given:
*      nwcs     int      Number of coordinate representations in the array.
*      wcs      const struct wcsprm**
*                        Pointer to an array of wcsprm structs returned by
*                        wcsbth().
*      type     int      Set this to zero to get indices for binary table
*                        image arrays, else pixel lists.
*
*   Returned:
*      alts     int[999][27]
*                        Index of each alternate coordinate represention in
*                        the array: alts[col][0] for the primary, alts[col][1]
*                        for 'A', etc., set to -1 if not present.
*
*                        For example, if there was no 'P' represention for
*                        column 13 then alts[13]['P'-'A'+1] would be set
*                        to -1.  Otherwise, the address of its wcsprm struct
*                        would be wcs + alts[13]['P'-'A'+1].
*
*
d629 1
a629 1
*       provide fine-grained control over what non-standard WCS keywords to
d641 1
a641 1
*         WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS
d649 1
a649 1
*         WCSHDO_TPCn_ka: WCS Paper I defined
d653 2
a654 2
*               but WCS Paper II uses TPCn_ka in one example and subsequently
*               the errata for the WCS papers legitimized the use of
d662 1
a662 1
*         WCSHDO_PVn_ma: WCS Paper I defined
d667 1
a667 1
*               but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and
d678 1
a678 1
*         WCSHDO_CRPXna: For historical reasons WCS Paper I defined
d680 2
a681 2
*                 jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn, for bintables and
*                 TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists
d684 2
a685 3
*               because of the eight-character keyword constraint, in order to
*               accommodate column numbers greater than 99 WCS Paper I also
*               defined
d687 2
a688 2
*                 jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and
*                 TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists
d690 1
a690 1
*               for use with an alternate version specifier (the "a").  Like
d693 1
a693 1
*               is very unlikely that any parser would reject keywords in the
d697 1
a697 1
*         WCSHDO_CNAMna: WCS Papers I and III defined
d707 2
a708 4
*               Note that these keywords provide auxiliary information only,
*               none of them are needed to compute world coordinates.  This
*               usage is potentially unsafe and is not recommended at this
*               time.
d710 1
a710 1
*         WCSHDO_WCSNna: WCS Paper I mistakenly defined the pixel list form of
d713 3
a715 3
*               keyword - note that keywords defined in WCS Papers II and III
*               that are not parameterised by axis number have identical forms
*               for binary tables and pixel lists.  This usage is potentially
d749 9
a757 9
#define WCSHDO_none     0x00
#define WCSHDO_all      0xFF
#define WCSHDO_safe     0x0F
#define WCSHDO_DOBSn    0x01
#define WCSHDO_TPCn_ka  0x02
#define WCSHDO_PVn_ma   0x04
#define WCSHDO_CRPXna   0x08
#define WCSHDO_CNAMna   0x10
#define WCSHDO_WCSNna   0x20
a766 1
int wcsbdx(int, struct wcsprm **, int, int [999][27]);
@


4.2.1.7
log
@Replaced use of the obsolete term "card".
@
text
@d30 1
a30 1
*   $Id: wcshdr.h,v 4.2.1.6 2007/12/04 01:50:10 cal103 Exp cal103 $
a45 2
*   Refer to the README file provided with WCSLIB for an overview of the
*   library.
d47 2
a48 3
*
*   Summary of wcshdr routines
*   --------------------------
d54 1
a54 1
*   wcsprm struct as a FITS header.
d62 1
a62 1
*         -TAB header keywords using wcstab().
d88 1
a88 1
*   wcstab() assists in filling in members of the wcsprm struct associated
d90 2
a91 2
*   a FITS binary table (BINTABLE) extension that are located by PVi_ma
*   keywords in the image header.
d100 1
a100 1
*   wcshdo() writes out a wcsprm struct as a FITS header.
d112 3
a114 3
*   identifies and reads all WCS keywords for the primary coordinate
*   representation and up to 26 alternate representations.  It returns this
*   information as an array of wcsprm structs.
d125 4
a128 5
*                        Each header "keyrecord" (formerly "card image")
*                        consists of exactly 80 7-bit ASCII printing
*                        characters in the range 0x20 to 0x7e (which excludes
*                        NUL, BS, TAB, LF, FF and CR) especially noting that
*                        the keyrecords are NOT null-terminated.
d131 2
a132 2
*                        modified so that WCS keyrecords processed by wcspih()
*                        are removed from it.
d135 1
a135 1
*      nkeyrec  int      Number of keyrecords in header[].
d143 3
a145 3
*      ctrl     int      Error reporting and other control options for invalid
*                        WCS and other header keyrecords:
*                           0: Do not report any rejected header keyrecords.
d147 6
a152 6
*                              of WCS keyrecords rejected (nreject).
*                           2: Report each rejected keyrecord and the reason
*                              why it was rejected.
*                           3: As above, but also report all non-WCS
*                              keyrecords that were discarded, and the number
*                              of coordinate representations (nwcs) found.
d155 7
a161 8
*                        For ctrl < 0, WCS keyrecords processed by wcspih()
*                        are removed from header[]:
*                          -1: Remove only valid WCS keyrecords whose values
*                              were successfully extracted, nothing is
*                              reported.  Exceptions: basic keyrecords
*                              {DATE,MJD}-{OBS,AVG} and OBSGEO-{X,Y,Z} are
*                              preserved.
*                          -2: Also remove WCS keyrecords that were rejected,
d166 2
a167 2
*                        If any keyrecords are removed from header[] it will
*                        be null-terminated (NUL not being a legal FITS header
d169 2
a170 2
*                        complement of nkeyrec keyrecords and possibly not be
*                        null-terminated.
d173 3
a175 4
*      nreject  int*     Number of WCS keywords rejected for syntax errors,
*                        illegal values, etc.  Keywords not recognized as WCS
*                        keywords are simply ignored (but see also note 5
*                        below).
d184 2
a185 2
*                        members to default values (see also note 7 below).
*                        Note that wcsset() is not invoked on these structs.
d226 1
a226 1
*   is stored in PVi_ma and PSi_ma keywords in the image header.
d228 2
a229 2
*   wcstab() parses the PVi_ma and PSi_ma keywords associated with each -TAB
*   axis and allocates memory in the wcsprm struct for the required number of
d259 2
a260 2
*   Index alternate coordinate representations; wcsidx()
*   ----------------------------------------------------
d271 2
a272 2
*                        Pointer to an array of wcsprm structs returned by
*                        wcspih() or wcsbth().
d275 7
a281 8
*      alts     int[27]  Index of each alternate coordinate representation in
*                        the array: alts[0] for the primary, alts[1] for 'A',
*                        etc., set to -1 if not present.
*
*                        For example, if there was no 'P' representation then
*                        alts['P'-'A'+1] would be set to -1.  Otherwise,
*                        the address of its wcsprm struct would be
*                        wcs + alts['P'-'A'+1].
d290 1
a290 1
*   --------------------------------------------------
d335 7
a341 7
*   Write out a wcsprm struct as a FITS header; wcshdo()
*   ----------------------------------------------------
*   wcshdo() translates a wcsprm struct into a FITS header.  If the colnum
*   member of the struct is non-zero then a binary table image array header
*   will be produced.  Otherwise, if the colax[] member of the struct is set
*   non-zero then a pixel list header will be produced.  Otherwise, a primary
*   image or image extension header will be produced.
d344 1
a344 1
*   the output header will almost certainly differ in a number of respects:
d346 3
a348 3
*     1) The output header only contains WCS-related keywords.  In particular,
*        it does not contain syntactically-required keywords such as SIMPLE,
*        NAXIS, BITPIX, or END.
d370 1
a370 1
*     8) Keyword order may be changed.
d372 3
a374 3
*   Keywords can be translated between the image array, binary table, and
*   pixel lists forms by manipulating the colnum or colax[] members of the
*   wcsprm struct.
d392 3
a394 3
*      nkeyrec  int*     Number of FITS header keyrecords returned in the
*                        "header" array.
*      header   char**   Pointer to an array of char holding the header.
d396 2
a397 2
*                        blocks of 2880 bytes (32 x 80-character keyrecords)
*                        and must be free'd by the user to avoid memory leaks.
d399 3
a401 3
*                        Each keyrecord is 80 characters long and is *NOT*
*                        null-terminated, so the first keyrecord starts at
*                        (*header)[0], the second at (*header)[80], etc.
d418 2
a419 2
*            keyrecord's keyvalue, as well as the keyword, must be
*            syntactically valid otherwise it will not be considered.
d518 1
a518 1
*       keyrecords to accept.  The flag bits are subject to change in future and
d522 2
a523 2
*         WCSHDR_none: Don't accept any extensions, treat non-conformant
*               keyrecords as though they did not exist in the header.
d528 4
a531 4
*         WCSHDR_reject: Reject non-standard keyrecords (that are not
*               otherwise accepted) and increment nreject.  This signals the
*               presence of such keyrecords, otherwise they are simply
*               discarded as though they did not exist in the header.
d649 2
a650 2
*    6) Neither wcspih() nor wcsbth() check for duplicated keywords, they
*       accept the last encountered.
d674 1
a674 1
*               obvious analogy) was never formally defined by the standard.
@


4.2.1.8
log
@Reordered the notes.
@
text
@d30 1
a30 1
*   $Id: wcshdr.h,v 4.2.1.7 2007/12/04 03:11:40 cal103 Exp cal103 $
d112 1
a112 1
*   drafts of the WCS papers (see note 4 below).
d146 1
a146 1
*                        is also possible, see note 4 below.
d180 1
a180 1
*                        keywords are simply ignored (but see also note 4
d190 1
a190 1
*                        members to default values (see also note 6 below).
d211 1
a211 1
*   drafts of the WCS papers (see note 4 below).
d219 1
a219 1
*   Note 7 below explains how wcsbth() aggregates table columns into one or
d390 1
a390 1
*                        is also possible, see note 8 below.
d432 82
a513 1
*    2) wcspih() and wcsbth() enforce correct FITS "keyword = value" syntax
d520 1
a520 1
*    3) Where CROTAn, CDi_ja, and PCi_ja occur together in one header wcspih()
d523 1
a523 1
*    4) wcspih() and wcsbth() interpret the "relax" argument as a vector of
d525 1
a525 1
*       keywords to accept.  The flag bits are subject to change in future and
d656 1
a656 1
*    5) Neither wcspih() nor wcsbth() check for duplicated keywords, they
d659 1
a659 1
*    6) wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue
a664 81
*    7) Parsing of pixel list headers is considerably more complicated than
*       that of image headers since a pixel list may contain multiple images.
*       Moreover, the pixel list convention does not specify how to identify
*       the columns containing pixel coordinates (as opposed to pixel values
*       or ancillary data), nor how to associate columns with image axes.
*
*       However, the WCS keywords can help at least in part.  Pixel coordinate
*       columns may be identifed simply by the presence of a WCS keyword for
*       that column.  They can also to be "tied" into a single image via WCS
*       keywords and/or keyvalues; specifically via TPn_ka or TCn_ka keywords,
*       or via TCTYna keyvalues as a celestial axis pair.  For example, the
*       presence of TP11_12 in a header identifies columns 11 and 22 as
*       containing pixel coordinates and directly ties them together.  If
*       TP12_22 was also present then the combination of the two TPn_ka
*       keywords would indirectly tie columns 11 and 22.  Therefore, these
*       three columns must form part of a single image.
*
*       Where the header contains a single celestial axis pair, e.g. with
*       TCTYna keyvalues 'RA---SIN' and 'DEC--SIN', then the tie is obvious.
*       If there are multiple celestial axis pairs and they are
*       distinguishable, e.g. with TCTYna keyvalues 'RA---SIN' and 'DEC--SIN'
*       on the one hand and 'GLON-ZEA' and 'GLAT-ZEA' on the other, then the
*       ties are also obvious.  However, if they are indistinguishable, e.g.
*       two pairs of 'RA---ZPN'/'DEC--ZPN' then it may not be so obvious how
*       to pair them.  wcsbth() associates the longitude and latitude columns
*
*         1: firstly by any TPn_ka or TCn_ka keywords that may connect them,
*
*         2: if that fails, then by proximity, i.e. by having consecutive
*            column numbers.
*
*       If an association cannot be deduced as above, then all of the columns
*       are considered to be part of one image, but wcsbth() returns a warning
*       status because wcsset() cannot handle multiple celestial pairs and
*       would return an error status for the resulting wcsprm struct.  The
*       celestial axis pairs would have to be separated (based on a priori
*       knowledge) using wcssub().
*
*       In similar vein, two columns may be "anti-tied" if they have an
*       auxiliary WCS keyword of the same form with the same alternate "a"
*       but with differing keyvalue, i.e.
*
*            DAVGn  EQUIna LATPna LONPna MJDAn  MJDOBn OBSGXn OBSGYn
*            OBSGZn RADEna RFRQna RWAVna SOBSna SPECna SSRCna TWCSna
*            VANGna VSYSna ZSOUna
*
*       These columns cannot form part of a single image because the WCS
*       standard (and the WCSLIB implementation) does not provide for more
*       than one of these keywords per image.  Likewise, the standard does
*       not provide for multiple celestial axis pairs or spectral axes in a
*       single image.  If multiples occur in one pixel list header then the
*       related columns are also anti-tied.
*
*       wcsbth() returns an error status if it finds two columns that are both
*       tied and anti-tied.
*
*       Finally there may be columns that are neither tied nor anti-tied.
*       In order to avoid de facto inheritance of auxiliary keyvalues by
*       association in the wcsprm struct, those columns with an auxiliary WCS
*       keyword are considered to form a one-dimensional image.  The remainder
*       are all collected into a single image.
*
*       These rules are best illustrated by example.  Consider a header
*       containing the following keywords (among others):
*
*         TP1_2, RFRQ1, TWCS1,
*         RFRQ7,
*         TWCS16, TP15_16, CTYP16='RA---SIN', CTYP17='DEC--SIN'
*         CTYP21='RA---SIN', CTYP22='DEC--SIN'
*
*       Separate images are defined by columns [1,2], [7], [15,16,17] and
*       [21,22].  Columns 1 and 2 are tied via TP1_2.  If RFRQ1 and RFRQ7 have
*       differing keyvalues then columns 1 and 7 are anti-tied; it would be an
*       error for TP2_7 also to be present in this header.  Columns 16 and 17
*       are tied via the CTYP16 and CTYP17 keyvalues and in turn column 15 is
*       tied them via TP15_16.  It would also be an error for column 1 to be
*       tied to either column 15, 16, or 17 unless TWCS1 and TWCS16 had the
*       same keyvalue.  The celestial axes in columns 21 and 22 are considered
*       to be paired by proximity and form a separate image because the others
*       all have an auxiliary keyword.
*
@


4.2.1.9
log
@wcsbth() extended to handle binary table image arrays - added a full
description of its interface with extensive reworking of the WCSHDR_*
relaxation arguments described in note 4.  Added a new note 5 concerning
the number of structs returned by wcsbth().  Reworked note 8 (new numbering)
concerning parsing of pixel list headers.
@
text
@d30 1
a30 1
*   $Id: wcshdr.h,v 4.2.1.8 2007/12/04 04:04:05 cal103 Exp cal103 $
d88 2
a89 4
*   wcsbth() is the analogue of wcspih() for use with binary tables; it
*   handles image array and pixel list keywords.  As an extension of the FITS
*   WCS standard, it also recognizes image header keywords which may be used
*   to provide default values via an inheritance mechanism.
d143 2
a144 2
*                           WCSHDR_all: Admit all recognized informal
*                              extensions of the WCS standard.
d163 3
a165 1
*                              reported.
a170 2
*                         -11: Same as -1 but preserving the basic keywords
*                              {DATE,MJD}-{OBS,AVG} and OBSGEO-{X,Y,Z}.
d190 1
a190 1
*                        members to default values (see also note 7 below).
d208 4
a211 99
*   header.  It handles image array and pixel list WCS keywords which may be
*   present together in one header.
*
*   As an extension of the FITS WCS standard, wcsbth() also recognizes image
*   header keywords in a binary table header.  These may be used to provide
*   default values via an inheritance mechanism discussed below in note 4 (see
*   WCSHDR_AUXIMG and WCSHDR_ALLIMG), or may instead result in wcsprm structs
*   that are not associated with any particular column.  Thus wcsbth() can
*   handle primary image and image extension headers in addition to binary
*   table headers (it ignores NAXIS and does not rely on the presence of the
*   TFIELDS keyword).
*
*   All WCS keywords defined in Papers I, II, and III are recognized, and also
*   those used by the AIPS convention and certain other keywords that existed
*   in early drafts of the WCS papers (see note 4 below).
*
*   wcsbth() sets the colnum or colax[] members of the wcsprm structs that it
*   returns to contain the column number of an image array or the column
*   numbers associated with each pixel coordinate element in a pixel list.
*   wcsprm structs that are not associated with any particular column, as may
*   be derived from image header keywords, have colnum == 0.
*
*   Note 5 below discusses the number of wcsprm structs returned by wcsbth(),
*   and the circumstances in which image header keywords cause a struct to be
*   created.  wcsbth() attempts to separate pixel lists into subimages where
*   necessary, refer to note 8 below.
*
*   The API to wcsbth() is similar to that of wcspih() except for the addition
*   of extra arguments that may be used to restrict its operation.  Like
*   wcspih(), wcsbth() invokes wcstab() on each of the wcsprm structs that it
*   returns.
*
*   Given and returned:
*      header   char[]   Character array containing the (entire) FITS binary
*                        table, primary image, or image extension header from
*                        which to idenfify and construct the coordinate
*                        representations, for example, as might be obtained
*                        conveniently via the CFITSIO routine fits_hdr2str().
*
*                        Each header "keyrecord" (formerly "card image"
*                        consists of exactly 80 7-bit ASCII printing
*                        characters in the range 0x20 to 0x7e (which excludes
*                        NUL, BS, TAB, LF, FF and CR) especially noting that
*                        the keyrecords are NOT null-terminated.
*
*                        For negative values of ctrl (see below), header[] is
*                        modified so that WCS keyrecords processed by wcsbth()
*                        are removed from it.
*
*   Given:
*      nkeyrec  int      Number of keyrecords in header[].
*      relax    int      Degree of permissiveness:
*                           0: Recognize only FITS keywords defined by the
*                              published WCS standard.
*                           WCSHDR_all: Admit all recognized informal
*                              extensions of the WCS standard.
*                        Fine-grained control of the degree of permissiveness
*                        is also possible, see note 4 below.
*      ctrl     int      Error reporting and other control options for invalid
*                        WCS and other header keyrecords:
*                           0: Do not report any rejected header keyrecords.
*                           1: Produce a one-line message stating the number
*                              of WCS keyrecords rejected (nreject).
*                           2: Report each rejected keyrecord and the reason
*                              why it was rejected.
*                           3: As above, but also report all non-WCS
*                              keyrecords that were discarded, and the number
*                              of coordinate representations (nwcs) found.
*                        The report is written to stderr.
*
*                        For ctrl < 0, WCS keyrecords processed by wcsbth()
*                        are removed from header[]:
*                          -1: Remove only valid WCS keyrecords whose values
*                              were successfully extracted, nothing is
*                              reported.
*                          -2: Also remove WCS keyrecords that were rejected,
*                              reporting each one and the reason that it was
*                              rejected.
*                          -3: As above, and also report the number of
*                              coordinate representations (nwcs) found.
*                         -11: Same as -1 but preserving the basic keywords
*                              {DATE,MJD}-{OBS,AVG} and OBSGEO-{X,Y,Z}.
*                        If any keyrecords are removed from header[] it will
*                        be null-terminated (NUL not being a legal FITS header
*                        character), otherwise it will contain its original
*                        complement of nkeyrec keyrecords and possibly not be
*                        null-terminated.
* ::: additional arguments
*
*   Returned:
*      nreject  int*     Number of WCS keywords rejected for syntax errors,
*                        illegal values, etc.  Keywords not recognized as WCS
*                        keywords are simply ignored (but see also note 4
*                        below).
* ::: additional arguments
*      nwcs     int*     Number of coordinate representations found.
*      wcs      struct wcsprm**
*                        Pointer to an array of wcsprm structs containing up
*                        to 27 coordinate representations.
d213 5
a217 5
*                        Memory for the array is allocated by wcsbth() which
*                        also invokes wcsini() for each struct to allocate
*                        memory for internal arrays and initialize their
*                        members to default values (see also note 7 below).
*                        Note that wcsset() is not invoked on these structs.
d219 2
a220 10
*                        This allocated memory must be freed by the caller,
*                        first by invoking wcsfree() for each struct, and then
*                        by freeing the array itself.  A routine, wcsvfree(),
*                        is provided to do this (see below).
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*                           2: Memory allocation failed.
a321 5
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
d390 1
a390 1
*                        is also possible, see note 9 below.
d448 12
a459 21
*         WCSHDR_none: Don't accept any extensions (not even those in the
*               errata).  Treat non-conformant keywords in the same way as
*               non-WCS keywords in the header, i.e. simply ignore them.
*
*         WCSHDR_reject: Reject non-standard keywords (that are not otherwise
*               accepted).  A message will optionally be printed on stderr, as
*               determined by the ctrl argument, and nreject will be
*               incremented.
*
*               This flag may be used to signal the presence of non-standard
*               keywords, otherwise they are simply passed over as though they
*               did not exist in the header.
*
*               Useful for testing conformance of a FITS header to the WCS
*               standard.
*
*         WCSHDR_all: Accept all extensions recognized by the parser.
*
*         WCSHDR_CROTAia: Accept CROTAia (wcspih),
*                                iCROTna (wcsbth),
*                                TCROTna (wcsbth).
d466 1
a466 1
*               wcsbth() accepts EPOCHa and VELREFa only if WCSHDR_AUXIMG is
d471 10
a480 16
*         WCSHDR_PROJPn:   Accept PROJPn   (wcspih).
*               These appeared in early drafts of WCS Paper I+II (before they
*               were split) and are equivalent to CDi_ja, PCi_ja, and PVi_ma
*               for the primary representation (a = ' ').  PROJPn is
*               equivalent to PVi_ma with m = n <= 9, and is associated
*               exclusively with the latitude axis.
*
*         WCSHDR_RADECSYS: Accept RADECSYS.  This appeared in early drafts of
*               WCS Paper I+II and was subsequently replaced by RADESYSa.
*
*               wcsbth() accepts RADECSYS only if WCSHDR_AUXIMG is also
*               enabled.
*
*         WCSHDR_VSOURCE: Accept VSOURCEa or VSOUna (wcsbth).  This appeared
*               in early drafts of WCS Paper III and was subsequently dropped
*               in favour of ZSOURCEa and ZSOUna.
d482 1
a482 4
*               wcsbth() accepts VSOURCEa only if WCSHDR_AUXIMG is also
*               enabled.
*
*         WCSHDR_DOBSn (wcsbth only): Allow DOBSn, the column-specific analogue
d487 1
a487 2
*               binary table and pixel list WCS keywords, i.e. with "a" non-
*               blank.  Specifically
d489 12
a500 9
*                 jCRPXna  TCRPXna   (jCRPXn, jCRPna, TCRPXn, TCRPna, CRPIXja)
*                          TPCn_ka   (        ijPCna,         TPn_ka, PCi_ja)
*                          TCDn_ka   (        ijCDna,         TCn_ka, CDi_ja)
*                 iCDLTna  TCDLTna   (iCDLTn, iCDEna, TCDLTn, TCDEna, CDELTia)
*                 iCUNIna  TCUNIna   (iCUNIn, iCUNna, TCUNIn, TCUNna, CUNITia)
*                 iCTYPna  TCTYPna   (iCTYPn, iCTYna, TCTYPn, TCTYna, CTYPEia)
*                 iCRVLna  TCRVLna   (iCRVLn, iCRVna, TCRVLn, TCRVna, CRVALia)
*                 iPVn_ma  TPVn_ma   (        iVn_ma,         TVn_ma, PVi_ma)
*                 iPSn_ma  TPSn_ma   (        iSn_ma,         TSn_ma, PSi_ma)
d503 6
a508 30
*               the image-header equivalent are shown in parentheses.
*
*               TPCn_ka, iPVn_ma, TPVn_ma appeared by mistake in the examples
*               in WCS Paper II and subsequently these and also TCDn_ka,
*               iPSn_ma and TPSn_ma were legitimized by the errata to the WCS
*               papers.  They could be described as quasi-standard.
*
*               The other long forms are non-standard and in fact have never
*               appeared in any draft of the WCS papers.  However, as natural
*               extensions of the primary form they are unlikely to be written
*               with any other intention.  Thus it should be safe to accept
*               them provided, of course, that the resulting keyword does not
*               exceed the 8-character limit.
*
*               If WCSHDR_CNAMn is enabled then also accept
*
*                 iCNAMna  TCNAMna   (        iCNAna,         TCNAna, CNAMEia)
*                 iCRDEna  TCRDEna   (        iCRDna,         TCRDna, CRDERia)
*                 iCSYEna  TCSYEna   (        iCSYna,         TCSYna, CSYERia)
*
*               Note that CNAMEia, CRDERia, CSYERia, and their variants are
*               not used by WCSLIB but are stored in the wcsprm struct as
*               auxiliary information.
*
*         WCSHDR_CNAMn (wcsbth only): Accept iCNAMn, iCRDEn, iCSYEn, TCNAMn,
*               TCRDEn, and TCSYEn, i.e. with "a" blank.  While non-standard,
*               these are the obvious analogues of iCTYPn, TCTYPn, etc.
*
*         WCSHDR_WCSNna (wcsbth only): Allow the use of WCSNna in pixel lists
*               in place of TWCSna.
d510 1
a510 1
*         WCSHDR_AUXIMG (wcsbth only): Allow the image-header form of an
d512 5
a516 8
*               provide a default value for all images.  This default may be
*               overridden by the column-specific form of the keyword.
*
*               For example, a keyword like EQUINOXa would apply to all image
*               arrays in a binary table, or all pixel list columns with
*               alternate representation "a" unless overridden by EQUIna.
*
*               Specifically the keywords are:
d518 4
d524 7
a533 10
*
*               whose keyvalues are actually used by WCSLIB, and also keywords
*               that provide auxiliary information that is simply stored in
*               the wcsprm struct:
*
*                  EPOCH        -      ... (No column-specific form.)
*                  EPOCHa       -      ... Only if WCSHDR_EPOCHa is set.
*                  EQUINOXa   EQUIna
*                  RADESYSa   RADEna
*                  RADECSYS   RADEna   ... Only if WCSHDR_RADECSYS is set.
d539 1
a539 2
*                  VELREF       -     ... (No column-specific form.)
*                  VELREFa      -     ... Only if WCSHDR_VELREFa is set.
d541 1
d545 1
a545 13
*                  DATE-AVG   DAVGn
*                  DATE-OBS   DOBSn
*                  MJD-AVG    MJDAn
*                  MJD-OBS    MJDOBn
*                  OBSGEO-X   OBSGXn
*                  OBSGEO-Y   OBSGYn
*                  OBSGEO-Z   OBSGZn
*
*               where the image-header keywords in the left-hand column
*               provide default values for the column specific keywords on
*               the right.
*
*               Keywords in the last group, such as MJD-OBS, apply to all
a548 77
*               This auxiliary inheritance mechanism applies to binary table
*               image arrays and pixel lists alike.  Most of these keywords
*               have no default value, the exceptions being LONPOLEa and
*               LATPOLEa, and also RADESYSa and EQUINOXa which provide
*               defaults for each other.  Thus the only potential difficulty
*               in using WCSHDR_AUXIMG is that of erroneously inheriting one
*               of these four keywords.
*
*               Unlike WCSHDR_ALLIMG, the existence of one (or all) of these
*               auxiliary WCS image header keywords will not by itself cause a
*               wcsprm struct to be created for alternate representation "a".
*               This is because they do not provide sufficient information to
*               create a non-trivial coordinate representation when used in
*               conjunction with the default values of those keywords, such as
*               CTYPEia, that are parameterized by axis number.
*
*         WCSHDR_ALLIMG (wcsbth only): Allow the image-header form of *all*
*               image header WCS keywords to provide a default value for all
*               image arrays in a binary table (n.b. not pixel list).  This
*               default may be overridden by the column-specific form of the
*               keyword.
*
*               For example, a keyword like CRPIXja would apply to all image
*               arrays in a binary table with alternate representation "a"
*               unless overridden by jCRPna.
*
*               Specifically the keywords are those listed above for
*               WCSHDR_AUXIMG plus
*
*                  WCSAXESa   WCAXna
*
*               which defines the coordinate dimensionality, and the following
*               keywords which are parameterized by axis number:
*
*                  CRPIXja    jCRPna
*                  PCi_ja     ijPCna
*                  CDi_ja     ijCDna
*                  CDELTia    iCDEna
*                  CROTAi     iCROTn
*                  CROTAia       -    ... Only if WCSHDR_CROTAia is set.
*                  CUNITia    iCUNna
*                  CTYPEia    iCTYna
*                  CRVALia    iCRVna
*                  PVi_ma     iVn_ma
*                  PSi_ma     iSn_ma
*
*                  CNAMEia    iCNAna
*                  CRDERia    iCRDna
*                  CSYERia    iCSYna
*
*               where the image-header keywords in the left-hand column
*               provide default values for the column specific keywords on
*               the right.
*
*               This full inheritance mechanism only applies to binary table
*               image arrays, not pixel lists, because in the latter case
*               there is no well-defined association between coordinate axis
*               number and column number.
*
*               Note that CNAMEia, CRDERia, CSYERia, and their variants are
*               not used by WCSLIB but are stored in the wcsprm struct as
*               auxiliary information.
*
*               Note especially that at least one wcsprm struct will be
*               returned for each "a" found in one of the image header
*               keywords listed above:
*
*               * If the image header keywords for "a" ARE NOT inherited by a
*                 binary table, then the struct will not be associated with
*                 any particular table column number and it is up to the user
*                 to provide an association.
*
*               * If the image header keywords for "a" ARE inherited by a
*                 binary table image array, then those keywords are considered
*                 to be 'exhausted' and do not result in a separate wcsprm
*                 struct.
*
d575 1
a575 32
*    5) Depending on what flags have been set in its 'relax' argument,
*       wcsbth() could return as many as 53973 wcsprm structs:
*
*         * Up to 27 unattached representations derived from image header
*           keywords.
*
*         * Up to 27 structs for each of up to 999 columns containing an image
*           arrays.
*
*         * Up to 27 structs for each of up to 999 columns containing a pixel
*           list, where each column cannot be aggregated with any other, e.g.
*           if each contained a spectrum.
*
*       Note that it is considered legitimate for a column to contain an image
*       array and also form part of a pixel list, and in particular that
*       wcsbth() does not (currently) check the the TFORM keyword for a pixel
*       list column to check that it is scalar.
*
*       In practice, of course, a realistic binary table header is unlikely to
*       contain more than a handful of images.
*
*       In order for wcsbth() to create a wcsprm struct for a particular
*       coordinate representation, at least one WCS keyword that defines an
*       axis number must be present, either directly or by inheritance if
*       WCSHDR_ALLIMG is set.
*
*       When the image header keywords for an alternate representation are
*       inherited by a binary table image array via WCSHDR_ALLIMG, those
*       keywords are considered to be 'exhausted' and do not result in a
*       separate wcsprm struct.  Otherwise they do.
*
*    6) Neither wcspih() nor wcsbth() check for duplicated keywords, they
d578 1
a578 1
*    7) wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue
d584 16
a599 30
*    8) The FITS WCS standard for pixel lists assumes that a pixel list
*       defines one and only one image, i.e. that each row of the binary table
*       refers to just one event, e.g. the detection of a single photon or
*       neutrino.
*
*       In the absence of a formal mechanism for identifying the columns
*       containing pixel coordinates (as opposed to pixel values or ancillary
*       data recorded at the time the photon or neutrino was detected),
*       Paper I discusses how the WCS keywords themselves may be used to
*       identify them.
*
*       In practice, however, pixel lists have been used to store multiple
*       images.  Besides not specifying how to identify columns, the pixel
*       list convention is also silent on the method to be used to associate
*       table columns with image axes.  If wcsbth() were simply to collect all
*       WCS keywords for a particular coordinate representation (i.e. the "a"
*       value in TCTYna) into one wcsprm struct then it could happen that the
*       struct contained more than two celestial axes.
*
*       However, the WCS keywords can also help here, at least in part.  While
*       pixel coordinate columns may be identifed simply by the presence of a
*       WCS keyword for that column, they can also to be "tied" into a single
*       image via WCS keywords and/or keyvalues; specifically via TPn_ka or
*       TCn_ka keywords, or via TCTYna keyvalues as a celestial axis pair.
*
*       For example, the presence of TP11_12 in a header identifies columns
*       11 and 22 as containing pixel coordinates and directly ties them
*       together.  If TP12_22 was also present then the combination of the two
*       TPn_ka keywords would indirectly tie columns 11 and 22.  Therefore,
*       these three columns must form part of a single image.
d665 1
a665 1
*    9) wcshdo() interprets the "relax" argument as a vector of flag bits to
d775 13
a787 17
#define WCSHDR_none     0x0000
#define WCSHDR_all      0xFFFE
#define WCSHDR_reject   0x0001
#define WCSHDR_CROTAia  0x0002
#define WCSHDR_EPOCHa   0x0004
#define WCSHDR_VELREFa  0x0008
#define WCSHDR_CD00i00j 0x0010
#define WCSHDR_PC00i00j 0x0020
#define WCSHDR_PROJPn   0x0040
#define WCSHDR_RADECSYS 0x0080
#define WCSHDR_VSOURCEa 0x0100
#define WCSHDR_DOBSn    0x0200
#define WCSHDR_LONGKEY  0x0400
#define WCSHDR_CNAMn    0x0800
#define WCSHDR_WCSNna   0x1000
#define WCSHDR_AUXIMG   0x2000
#define WCSHDR_ALLIMG   0x4000
@


4.2.1.10
log
@Switched to LGPL 3.0.
@
text
@d2 29
a30 30

    WCSLIB 4.3 - an implementation of the FITS WCS standard.
    Copyright (C) 1995-2007, Mark Calabretta

    This file is part of WCSLIB.

    WCSLIB is free software: you can redistribute it and/or modify it under
    the terms of the GNU Lesser General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
    more details.

    You should have received a copy of the GNU Lesser General Public License
    along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.

    Correspondence concerning WCSLIB may be directed to:
       Internet email: mcalabre@@atnf.csiro.au
       Postal address: Dr. Mark Calabretta
                       Australia Telescope National Facility, CSIRO
                       PO Box 76
                       Epping NSW 1710
                       AUSTRALIA

    Author: Mark Calabretta, Australia Telescope National Facility
    http://www.atnf.csiro.au/~mcalabre/index.html
    $Id: wcshdr.h,v 4.2.1.9 2007/12/04 04:16:17 cal103 Exp cal103 $
@


4.2.1.11
log
@Reworked note 8, no attempt will be made to separate multiple images in a
pixel list - this is not well-defined, particularly concerning the association
of auxiliary WCS keywords with particular images.
@
text
@d31 1
a31 1
    $Id: wcshdr.h,v 4.2.1.10 2007/12/04 04:21:41 cal103 Exp cal103 $
d60 1
a60 1
*   Briefly, the anticipated sequence of operations is as follows:
d65 2
a66 2
*      2: Parse the header using wcspih() or wcsbth(); they will automatically
*         interpret -TAB header keywords using wcstab().
d228 4
a231 4
*   returns with the column number of an image array or the column numbers
*   associated with each pixel coordinate element in a pixel list.  wcsprm
*   structs that are not associated with any particular column, as may be
*   derived from image header keywords, have colnum == 0.
d235 2
a236 2
*   created.  See also note 8 concerning the number of separate images that
*   may be stored in a pixel list.
d818 1
a818 1
*       wcsbth() could return as many as 27027 wcsprm structs:
d826 3
a828 1
*         * Up to 27 structs for a pixel list.
d832 2
a833 2
*       wcsbth() does not check the the TFORM keyword for a pixel list column
*       to check that it is scalar.
d871 80
a950 11
*       table columns with image axes.
*
*       wcsbth() simply collects all WCS keywords for a particular coordinate
*       representation (i.e. the "a" value in TCTYna) into one wcsprm struct.
*       However, these alternates need not be associated with the same table
*       columns and this allows a pixel list to contain up to 27 separate
*       images.  As usual, if one of these representations happened to contain
*       more than two celestial axes, for example, then an error would result
*       when wcsset() is invoked on it.  In this case the ::: argument could
*       be used to restrict the columns used to construct the representation
*       so that it only contained one pair of celestial axes.
@


4.2.1.12
log
@Documented the "keysel" and "colsel" arguments to wcsbth().  Added a new
note 4 concerning WCSNna and TWCSna and renumbered the old ones.  Reworked
the WCSHDR flag vectors.
@
text
@d31 1
a31 1
    $Id: wcshdr.h,v 4.2.1.11 2007/12/04 04:59:09 cal103 Exp cal103 $
d115 1
a115 1
*   drafts of the WCS papers (see note 5 below).
d149 1
a149 1
*                        is also possible, see note 5 below.
d183 1
a183 1
*                        keywords are simply ignored (but see also note 5
d193 1
a193 1
*                        members to default values (see also note 8 below).
d216 1
a216 1
*   default values via an inheritance mechanism discussed below in note 5 (see
d225 1
a225 1
*   in early drafts of the WCS papers (see note 5 below).
d233 1
a233 1
*   Note 6 below discusses the number of wcsprm structs returned by wcsbth(),
d235 1
a235 1
*   created.  See also note 9 concerning the number of separate images that
d268 1
a268 1
*                        is also possible, see note 5 below.
d298 1
a298 27
*      keysel   int      Given, a vector of flag bits that may be used to
*                        restrict the keyword types considered:
*                          WCSHDR_IMGHEAD: Image header keywords.
*                          WCSHDR_BIMGARR: Binary table image array.
*                          WCSHDR_PIXLIST: Pixel list keywords.
*                        If zero, there is no restriction.
*
*                        Keywords such as EQUIna or RFRQna that are common to
*                        binary table image arrays and pixel lists (including
*                        WCSNna and TWCSna, see note 4 below), are selected by
*                        both WCSHDR_BIMGARR and WCSHDR_PIXLIST.
*      colsel   int*     Pointer to an array of table column numbers used to
*                        restrict the keywords considered by wcsbth().
*
*                        A null pointer may be specified to indicate that
*                        there is no restriction.  Otherwise, the magnitude of
*                        cols[0] specifies the length of the array:
*                          cols[0] > 0: the columns are included,
*                          cols[0] < 0: the columns are excluded.
*
*                        For the pixel list keywords TPn_ka and TCn_ka (and
*                        TPCn_ka and TCDn_ka if WCSHDR_LONGKEY is enabled), 
*                        it is an error for one column to be selected but not
*                        the other.  This is unlike the situation with invalid
*                        keyrecords, which are simply rejected, because the
*                        error is not intrinsic to the header itself but
*                        arises in the way that it is processed.
d303 1
a303 1
*                        keywords are simply ignored (but see also note 5
d305 1
d309 1
a309 2
*                        to 27027 coordinate representations (see note 6
*                        below).
d314 1
a314 1
*                        members to default values (see also note 8 below).
a326 1
*                           3: Invalid column selection.
d485 1
a485 1
*     7) The original keycomments will be lost, although wcshdo() tries hard
d501 1
a501 1
*                        is also possible, see note 10 below.
d553 1
a553 8
*    4) WCS Paper I mistakenly defined the pixel list form of WCSNAMEa as
*       TWCSna instead of WCSNna; the 'T' is meant to substitute for the axis
*       number in the binary table form of the keyword - note that keywords
*       defined in WCS Papers II and III that are not parameterised by axis
*       number have identical forms for binary tables and pixel lists.
*       Consequently wcsbth() always treats WCSNna and TWCSna as equivalent.
*
*    5) wcspih() and wcsbth() interpret the "relax" argument as a vector of
d632 11
a642 13
*               The long form of these keywords could be described as quasi-
*               standard.  TPCn_ka, iPVn_ma, and TPVn_ma appeared by mistake
*               in the examples in WCS Paper II and subsequently these and
*               also TCDn_ka, iPSn_ma and TPSn_ma were legitimized by the
*               errata to the WCS papers.
*
*               Strictly speaking, the other long forms are non-standard and
*               in fact have never appeared in any draft of the WCS papers nor
*               in the errata.  However, as natural extensions of the primary
*               form they are unlikely to be written with any other intention.
*               Thus it should be safe to accept them provided, of course,
*               that the resulting keyword does not exceed the 8-character
*               limit.
d658 3
d682 2
a683 2
*                  EPOCH        -     ... (No column-specific form.)
*                  EPOCHa       -     ... Only if WCSHDR_EPOCHa is set.
d686 1
a686 1
*                  RADECSYS   RADEna  ... Only if WCSHDR_RADECSYS is set.
d695 1
a695 1
*                  WCSNAMEa   WCSNna  ... Or TWCSna (see below).
d788 1
a788 1
*                 to be "exhausted" and do not result in a separate wcsprm
d817 1
a817 1
*    6) Depending on what flags have been set in its "relax" argument,
d843 1
a843 1
*       keywords are considered to be "exhausted" and do not result in a
d846 2
a847 2
*    7) Neither wcspih() nor wcsbth() check for duplicated keywords, in most
*       cases they accept the last encountered.
d849 1
a849 1
*    8) wcspih() and wcsbth() use wcsnpv() and wcsnps() (refer to the prologue
d855 1
a855 1
*    9) The FITS WCS standard for pixel lists assumes that a pixel list
d877 3
a879 3
*       when wcsset() is invoked on it.  In this case the "colsel" argument
*       could be used to restrict the columns used to construct the
*       representation so that it only contained one pair of celestial axes.
d881 1
a881 1
*   10) wcshdo() interprets the "relax" argument as a vector of flag bits to
d966 7
a972 5
*         WCSHDO_WCSNna: In light of note 4 above, write WCSNna instead of
*               TWCSna for pixel lists.  While wcsbth() treats WCSNna and
*               TWCSna as equivalent, other parsers may not.  Consequently,
*               this usage is potentially unsafe and is not recommended at
*               this time.
d991 17
a1007 22
#define WCSHDR_none     0x00000000
#define WCSHDR_all      0x000FFFFF
#define WCSHDR_reject   0x10000000

#define WCSHDR_CROTAia  0x00000001
#define WCSHDR_EPOCHa   0x00000002
#define WCSHDR_VELREFa  0x00000004
#define WCSHDR_CD00i00j 0x00000008
#define WCSHDR_PC00i00j 0x00000010
#define WCSHDR_PROJPn   0x00000020
#define WCSHDR_RADECSYS 0x00000040
#define WCSHDR_VSOURCEa 0x00000080
#define WCSHDR_DOBSn    0x00000100
#define WCSHDR_LONGKEY  0x00000200
#define WCSHDR_CNAMn    0x00000400
#define WCSHDR_AUXIMG   0x00000800
#define WCSHDR_ALLIMG   0x00001000

#define WCSHDR_IMGHEAD  0x00010000
#define WCSHDR_BIMGARR  0x00020000
#define WCSHDR_PIXLIST  0x00040000
#define WCSHDR_BINTAB   0x00080000
d1024 1
a1024 1
int wcsbth(char *, int, int, int, int, int *, int *, int*, struct wcsprm **);
@


4.2.1.13
log
@Reworked the API to wcsbdx() to make it a little more practical in everyday
use.  Augmented the description of the keysel argument to wcsbth(), and also
note 1.
@
text
@d31 1
a31 1
    $Id: wcshdr.h,v 4.2.1.12 2007/12/26 04:20:03 cal103 Exp cal103 $
d308 1
a308 6
*                        both WCSHDR_BIMGARR and WCSHDR_PIXLIST.  Thus if
*                        inheritance via WCSHDR_ALLIMG is enabled (see note 5
*                        below) and one of these shared keywords is present,
*                        then WCSHDR_IMGHEAD and WCSHDR_PIXLIST alone may be
*                        sufficient to cause the construction of coordinate
*                        descriptions for binary table image arrays.
d441 2
a442 3
*      type     int      Select the type of coordinate representation:
*                          0: binary table image arrays,
*                          1: pixel lists.
d445 1
a445 1
*      alts     short[1000][28]
d448 1
a448 6
*                        for 'A', to alts[col][26] for 'Z', where col is the
*                        1-relative column number, and col == 0 is used for
*                        unattached image headers.  Set to -1 if not present.
*
*                        alts[col][27] counts the number of coordinate
*                        representations of the chosen type for each column.
d563 2
a564 9
*            keyvalue, as well as the keyword, must be syntactically valid
*            otherwise it will not be considered.
*
*       If none of these keyword types is present, i.e. if the header only
*       contains auxiliary WCS keywords for a particular coordinate
*       representation, then no coordinate description is constructed for it.
*
*       wcsbth() is similar except that it ignores the NAXIS keyword if given
*       an image header to process.
d1063 1
a1063 1
int wcsbdx(int, struct wcsprm **, int, short [1000][28]);
@


4.1
log
@WCSLIB 4.1: added a general overview of the highest-level WCSLIB routines
and how they are expected to be used; revised usage notes for wcspih() - the
ctrl argument (previously errlvl) if negative causes WCS cards to be removed
from the header; usage notes for wcstab(); specific error messages,
wcshdr_errmsg[]; changed #include of WCSLIB headers from "" to <> form as
required for installed header files.
@
text
@d3 1
a3 1
*   WCSLIB 4.1 - an implementation of the FITS WCS standard.
d30 1
a30 1
*   $Id: wcshdr.h,v 4.0 2005/02/04 06:15:26 cal103 Exp cal103 $
d33 1
a33 1
*   WCSLIB 4.1 - C routines that implement the FITS World Coordinate System
d373 1
a373 1
#include <wcs.h>
@


4.0
log
@WCSLIB 4.0: changed from LGPL to GPL; description and prototype for new
function wcsidx().
@
text
@d3 1
a3 1
*   WCSLIB 4.0 - an implementation of the FITS WCS standard.
d30 1
a30 1
*   $Id: wcshdr.h,v 3.6 2004/08/25 04:59:52 cal103 Exp cal103 $
d33 1
a33 1
*   WCSLIB 4.0 - C routines that implement the FITS World Coordinate System
d49 28
d78 7
a84 1
*   returns an array of up to 27 wcsprm structs.
a92 4
*   Refer to the prologue of wcs.h for a description of the high level driver
*   routines for the WCS linear, celestial, and spectral transformation
*   routines.
*
d100 1
a100 1
*   drafts of the WCS papers (see note 3 below).
d102 1
a102 1
*   Given a character array containing a FITS header wcspih() identifies and
d107 3
a109 1
*   Given:
d114 12
a125 1
*      nkeys    int      Number of keywords in the header.
d132 3
a134 2
*                        is also possible, see note 3 below.
*      errlvl   int      Error reporting control:
d145 15
d163 1
a163 1
*                        cards are simply ignored (but see also note 3 below).
d172 2
a173 2
*                        members to default values (but note that wcsset() is
*                        not invoked on these structs).
d177 2
a178 2
*                        by freeing the array itself.  A service routine,
*                        wcsvfree(), is provided to do this (see below).
d187 44
a230 2
*   Utility routine for indexing alternate coordinate descriptions; wcsidx()
*   ------------------------------------------------------------------------
d255 2
a256 2
*   Service routine for the array of wcsprm structs; wcsvfree()
*   -----------------------------------------------------------
d275 11
a285 1
*    1) The parser enforces correct FITS "keyword = value" syntax with regard
d292 2
a293 2
*    2) Where CROTAn, CDi_ja, and PCi_ja occur together in one header the
*       parser treats them as described in the prologue to wcs.h.
d295 1
a295 1
*    3) The parser interprets its "relax" argument as a vector of flag bits to
d350 1
a350 1
*       The parser does not currently recognize the AIPS-convention keywords
d354 1
a354 1
*    4) The parser does not check for duplicated cards, it accepts the last
d357 5
d366 1
a366 1
*   encoded in the wcs_errmsg character array.
d373 1
a373 1
#include "wcs.h"
a378 1

d389 2
d393 1
@


3.6
log
@WCSLIB 3.6: added additional notes to the prologue concerning FITS header
syntax, the occurrence of CROTAn, CDi_ja, and PCi_ja together in one header,
and treatment of duplicated cards; define the WCSHDR flags as hex constants
and added one for VSOURCEa; "error status/code/number" is now referred to
consistently as the "status return value"; replaced "error" with "failed" in
status messages; removed support for K&R C.
@
text
@d3 2
a4 2
*   WCSLIB 3.6 - an implementation of the FITS WCS convention.
*   Copyright (C) 1995-2004, Mark Calabretta
d6 13
a18 13
*   This library is free software; you can redistribute it and/or modify it
*   under the terms of the GNU Library General Public License as published
*   by the Free Software Foundation; either version 2 of the License, or (at
*   your option) any later version.
*
*   This library is distributed in the hope that it will be useful, but
*   WITHOUT ANY WARRANTY; without even the implied warranty of
*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library
*   General Public License for more details.
*
*   You should have received a copy of the GNU Library General Public License
*   along with this library; if not, write to the Free Software Foundation,
*   Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
d30 1
a30 1
*   $Id: wcshdr.h,v 3.5 2004/06/28 04:23:46 mcalabre Exp mcalabre $
d33 2
a34 2
*   WCSLIB 3.6 - C routines that implement the FITS World Coordinate System
*   (WCS) convention.  Refer to
d43 1
a43 1
*      Greisen, E.W., Valdes, F.G., Calabretta, M.R., & Allen, S.L. 2004, A&A,
d52 4
d72 2
a73 2
*   Given a character array containing a FITS header it identifies and reads
*   all WCS cards for the primary coordinate description and up to 26
d128 26
d226 1
a226 1
*       the AIPS convention VELREF has the following values:
d276 1
@


3.5
log
@WCSLIB 3.5: initial revision.
@
text
@d3 1
a3 1
*   WCSLIB 3.5 - an implementation of the FITS WCS convention.
d30 1
a30 1
*   $Id$
d33 1
a33 1
*   WCSLIB 3.5 - C routines that implement the FITS World Coordinate System
d66 1
a66 1
*   drafts of the WCS papers (see note 1 below).
d85 1
a85 1
*                        is also possible, see note 1 below.
d100 1
a100 1
*                        cards are simply ignored (but see also note 1 below).
d118 1
a118 1
*               int      Error status
d121 1
a121 1
*                           2: Memory allocation error.
d137 1
a137 1
*               int      Error status
d144 11
a154 1
*    1) The parser interprets its "relax" argument as a vector of flag bits to
d183 3
a185 1
*       For example
d187 3
a191 3
*       Note that where CROTAn, CDi_ja, and PCi_ja occur together in one
*       header the parser treats them as described in the prologue to wcs.h.
*
d193 1
a193 1
*       present.
d213 3
d217 3
a219 3
*   Error codes
*   -----------
*   Error messages to match the error codes returned from each function are
a228 9
#define WCSHDR_all      1
#define WCSHDR_reject   2
#define WCSHDR_CROTAia  4
#define WCSHDR_EPOCHa   8
#define WCSHDR_VELREFa  16
#define WCSHDR_CD00i00j 32
#define WCSHDR_PC00i00j 64
#define WCSHDR_PROJPn   128

d233 15
a247 6
#if __STDC__ || defined(__cplusplus)
   int wcspih(char *, int, int, int, int *, int *, struct wcsprm **);
   int wcsvfree(int *, struct wcsprm **);
#else
   int wcspih(), wcsvfree();
#endif
@


0.0
log
@Empty revision
@
text
@d1 238
@
