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.30.07.32.42;	author cal103;	state Exp;
branches;
next	4.0;

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

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

3.5
date	2004.06.28.04.09.39;	author mcalabre;	state Exp;
branches;
next	3.4;

3.4
date	2004.02.11.00.15.03;	author mcalabre;	state Exp;
branches;
next	3.3;

3.3
date	2003.10.21.08.51.00;	author mcalabre;	state Exp;
branches;
next	3.2;

3.2
date	2003.09.09.04.37.19;	author mcalabre;	state Exp;
branches;
next	3.1;

3.1
date	2003.04.28.03.50.41;	author mcalabre;	state Exp;
branches;
next	3.0;

3.0
date	2003.04.01.04.10.53;	author mcalabre;	state Exp;
branches;
next	2.9;

2.9
date	2002.04.03.01.25.29;	author mcalabre;	state Exp;
branches;
next	2.8;

2.8
date	2001.11.15.03.29.43;	author mcalabre;	state Exp;
branches;
next	2.7;

2.7
date	2000.05.10.04.44.05;	author mcalabre;	state Exp;
branches;
next	2.6;

2.6
date	99.05.26.01.32.18;	author mcalabre;	state Exp;
branches;
next	2.5;

2.5
date	99.05.26.01.24.48;	author mcalabre;	state Exp;
branches;
next	2.4;

2.4
date	96.05.24.07.25.36;	author mcalabre;	state Exp;
branches;
next	2.3;

2.3
date	96.05.10.15.54.56;	author mcalabre;	state Exp;
branches;
next	2.2;

2.2
date	96.05.07.20.07.34;	author mcalabre;	state Exp;
branches;
next	2.1;

2.1
date	95.11.16.04.44.40;	author mcalabre;	state Exp;
branches;
next	2.0;

2.0
date	95.09.11.08.46.25;	author mcalabre;	state Exp;
branches;
next	1.2;

1.2
date	95.09.11.07.58.43;	author mcalabre;	state Exp;
branches;
next	1.1;

1.1
date	95.01.25.04.00.55;	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.04.27.03.46.13;	author cal103;	state Exp;
branches;
next	4.2.1.3;

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

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

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

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

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

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

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

4.2.1.10
date	2007.12.22.07.28.38;	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	2009.08.13.04.20.33;	author cal103;	state Exp;
branches;
next	4.4.1.3;

4.4.1.3
date	2009.09.03.05.02.16;	author cal103;	state Exp;
branches;
next	4.4.1.4;

4.4.1.4
date	2010.01.19.03.42.50;	author cal103;	state Exp;
branches;
next	4.4.1.5;

4.4.1.5
date	2010.07.07.13.30.37;	author cal103;	state Exp;
branches;
next	;

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

4.5.1.2
date	2010.11.02.06.48.43;	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.6.1.3;

4.6.1.3
date	2011.01.25.06.35.25;	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.44.21;	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.52.12;	author cal103;	state Exp;
branches;
next	4.7.1.5;

4.7.1.5
date	2011.08.15.06.01.51;	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	2011.11.17.03.26.50;	author cal103;	state Exp;
branches;
next	4.8.1.3;

4.8.1.3
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.9.1.2;

4.9.1.2
date	2012.01.31.23.56.50;	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.05.09.44;	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.18.1.2;

4.18.1.2
date	2013.07.15.14.17.06;	author mcalabre;	state Exp;
branches;
next	4.18.1.3;

4.18.1.3
date	2013.09.29.10.17.56;	author mcalabre;	state Exp;
branches;
next	;

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

4.19.1.2
date	2013.12.10.23.06.18;	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.20.1.3;

4.20.1.3
date	2014.03.22.05.03.00;	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.22.1.2;

4.22.1.2
date	2014.05.10.14.30.40;	author mcalabre;	state Exp;
branches;
next	;

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

4.23.1.2
date	2014.05.22.10.53.09;	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.05.08.20.35;	author mcalabre;	state Exp;
branches;
next	4.25.1.4;

4.25.1.4
date	2015.04.03.01.41.19;	author mcalabre;	state Exp;
branches;
next	4.25.1.5;

4.25.1.5
date	2015.04.05.06.01.11;	author mcalabre;	state Exp;
branches;
next	4.25.1.6;

4.25.1.6
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.27.21;	author mcalabre;	state Exp;
branches;
next	5.1.1.3;

5.1.1.3
date	2015.04.13.09.36.30;	author mcalabre;	state Exp;
branches;
next	5.1.1.4;

5.1.1.4
date	2015.04.13.11.46.15;	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.6.1.2;

5.6.1.2
date	2015.06.16.07.45.15;	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.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	2017.12.05.07.42.06;	author mcalabre;	state Exp;
branches;
next	5.17.1.3;

5.17.1.3
date	2017.12.05.23.33.23;	author mcalabre;	state Exp;
branches;
next	5.17.1.4;

5.17.1.4
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.06.22.54;	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.34.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.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.02.21.58;	author mcalabre;	state Exp;
branches;
next	6.4.1.3;

6.4.1.3
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.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.12.10.44;	author mcalabre;	state Exp;
branches;
next	7.3.1.3;

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

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

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

7.3.1.6
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.4.1.2;

7.4.1.2
date	2021.02.22.07.23.26;	author mcalabre;	state Exp;
branches;
next	;

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

7.5.1.2
date	2021.04.09.03.54.49;	author mcalabre;	state Exp;
branches;
next	7.5.1.3;

7.5.1.3
date	2021.04.10.14.25.00;	author mcalabre;	state Exp;
branches;
next	7.5.1.4;

7.5.1.4
date	2021.04.13.09.27.51;	author mcalabre;	state Exp;
branches;
next	;

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

7.6.1.2
date	2021.07.01.08.28.44;	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.22.05.13.08;	author mcalabre;	state Exp;
branches;
next	7.7.1.3;

7.7.1.3
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.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.03.05.37.07;	author mcalabre;	state Exp;
branches;
next	7.13.1.3;

7.13.1.3
date	2023.06.03.08.24.14;	author mcalabre;	state Exp;
branches;
next	7.13.1.4;

7.13.1.4
date	2023.06.15.03.58.10;	author mcalabre;	state Exp;
branches;
next	7.13.1.5;

7.13.1.5
date	2023.06.15.04.17.19;	author mcalabre;	state Exp;
branches;
next	7.13.1.6;

7.13.1.6
date	2023.07.01.06.09.15;	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.2.1.3;

8.2.1.3
date	2024.05.08.15.26.39;	author mcalabre;	state Exp;
branches;
next	8.2.1.4;

8.2.1.4
date	2024.05.13.14.28.50;	author mcalabre;	state Exp;
branches;
next	8.2.1.5;

8.2.1.5
date	2024.05.13.16.15.46;	author mcalabre;	state Exp;
branches;
next	;

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

8.3.1.2
date	2024.07.09.06.25.46;	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 high-level driver routines for WCS
coordinate transformations; contains the definition of the "wcsprm" struct.
@


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: wcs.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 wcs routines
* ---------------------------
* Routines in this suite implement the FITS World Coordinate System (WCS)
* standard which defines methods to be used for computing world coordinates
* from image pixel coordinates, and vice versa.  The standard, and proposed
* extensions for handling distortions, are described 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
=
=   "Mapping on the HEALPix grid",
=   Calabretta, M.R., & Roukema, B.F. 2007, MNRAS, 381, 865 (WCS Paper V)
=
=   "Representing the 'Butterfly' Projection in FITS -- Projection Code XPH",
=   Calabretta, M.R., & Lowe, S.R. 2013, PASA, 30, e050 (WCS Paper VI)
=
=   "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 are based on the wcsprm struct which contains all information
* needed for the computations.  The struct contains some members that must be
* set by the user, and others that are maintained by these routines, somewhat
* like a C++ class but with no encapsulation.
*
* wcsnpv(), wcsnps(), wcsini(), wcsinit(), wcssub(), wcsfree(), and wcstrim(),
* are provided to manage the wcsprm struct, wcssize() computes its total size
* including allocated memory, wcsenq() returns information about the state of
* the struct, and wcsprt() prints its contents.  wcscopy(), which does a deep
* copy of one wcsprm struct to another, is defined as a preprocessor macro
* function that invokes wcssub().
*
* wcsperr() prints the error message(s) (if any) stored in a wcsprm struct,
* and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
*
* A setup routine, wcsset(), computes intermediate values in the wcsprm struct
* from parameters in it that were supplied by the user.  The struct always
* needs to be set up by wcsset() but this need not be called explicitly -
* refer to the explanation of wcsprm::flag.
*
* wcsp2s() and wcss2p() implement the WCS world coordinate transformations.
* In fact, they are high level driver routines for the WCS linear,
* logarithmic, celestial, spectral and tabular transformation routines
* described in lin.h, log.h, cel.h, spc.h and tab.h.
*
* Given either the celestial longitude or latitude plus an element of the
* pixel coordinate a hybrid routine, wcsmix(), iteratively solves for the
* unknown elements.
*
* wcsccs() changes the celestial coordinate system of a wcsprm struct, for
* example, from equatorial to galactic, and wcssptr() translates the spectral
* axis.  For example, a 'FREQ' axis may be translated into 'ZOPT-F2W' and vice
* versa.
*
* wcslib_version() returns the WCSLIB version number.
*
* Quadcube projections:
* ---------------------
*   The quadcube projections (TSC, CSC, QSC) may be represented in FITS in
*   either of two ways:
*
*     a: The six faces may be laid out in one plane and numbered as follows:
*
=                                 0
=
=                        4  3  2  1  4  3  2
=
=                                 5
*
*        Faces 2, 3 and 4 may appear on one side or the other (or both).  The
*        world-to-pixel routines map faces 2, 3 and 4 to the left but the
*        pixel-to-world routines accept them on either side.
*
*     b: The "COBE" convention in which the six faces are stored in a
*        three-dimensional structure using a CUBEFACE axis indexed from
*        0 to 5 as above.
*
*   These routines support both methods; wcsset() determines which is being
*   used by the presence or absence of a CUBEFACE axis in ctype[].  wcsp2s()
*   and wcss2p() translate the CUBEFACE axis representation to the single
*   plane representation understood by the lower-level WCSLIB projection
*   routines.
*
*
* wcsnpv() - Memory allocation for PVi_ma
* ---------------------------------------
* wcsnpv() sets or gets the value of NPVMAX (default 64).  This global
* variable controls the number of pvcard structs, for holding PVi_ma
* keyvalues, that wcsini() should allocate space for.  It is also used by
* wcsinit() as the default value of npvmax.
*
* PLEASE NOTE: This function is not thread-safe.
*
* Given:
*   n         int       Value of NPVMAX; ignored if < 0.  Use a value less
*                       than zero to get the current value.
*
* Function return value:
*             int       Current value of NPVMAX.
*
*
* wcsnps() - Memory allocation for PSi_ma
* ---------------------------------------
* wcsnps() sets or gets the value of NPSMAX (default 8).  This global variable
* controls the number of pscard structs, for holding PSi_ma keyvalues, that
* wcsini() should allocate space for.  It is also used by wcsinit() as the
* default value of npsmax.
*
* PLEASE NOTE: This function is not thread-safe.
*
* Given:
*   n         int       Value of NPSMAX; ignored if < 0.  Use a value less
*                       than zero to get the current value.
*
* Function return value:
*             int       Current value of NPSMAX.
*
*
* wcsini() - Default constructor for the wcsprm struct
* ----------------------------------------------------
* wcsini() is a thin wrapper on wcsinit().  It invokes it with npvmax,
* npsmax, and ndpmax set to -1 which causes it to use the values of the
* global variables NDPMAX, NPSMAX, and NDPMAX.  It is thereby potentially
* thread-unsafe if these variables are altered dynamically via wcsnpv(),
* wcsnps(), and disndp().  Use wcsinit() for a thread-safe alternative in
* this case.
*
*
* wcsinit() - Default constructor for the wcsprm struct
* -----------------------------------------------------
* wcsinit() optionally allocates memory for arrays in a wcsprm struct and sets
* all members of the struct to default values.
*
* PLEASE NOTE: every wcsprm struct should be initialized by wcsinit(),
* possibly repeatedly.  On the first invokation, and only the first
* invokation, wcsprm::flag must be set to -1 to initialize memory management,
* regardless of whether wcsinit() will actually be used to allocate memory.
*
* Given:
*   alloc     int       If true, allocate memory unconditionally for the
*                       crpix, etc. arrays.  Please note that memory is never
*                       allocated by wcsinit() for the auxprm, tabprm, nor
*                       wtbarr structs.
*
*                       If false, it is assumed that pointers to these arrays
*                       have been set by the user except if they are null
*                       pointers in which case memory will be allocated for
*                       them regardless.  (In other words, setting alloc true
*                       saves having to initalize these pointers to zero.)
*
*   naxis     int       The number of world coordinate axes.  This is used to
*                       determine the length of the various wcsprm vectors and
*                       matrices and therefore the amount of memory to
*                       allocate for them.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
*                       Note that, in order to initialize memory management,
*                       wcsprm::flag should be set to -1 when wcs is
*                       initialized for the first time (memory leaks may
*                       result if it had already been initialized).
*
* Given:
*   npvmax    int       The number of PVi_ma keywords to allocate space for.
*                       If set to -1, the value of the global variable NPVMAX
*                       will be used.  This is potentially thread-unsafe if
*                       wcsnpv() is being used dynamically to alter its value.
*
*   npsmax    int       The number of PSi_ma keywords to allocate space for.
*                       If set to -1, the value of the global variable NPSMAX
*                       will be used.  This is potentially thread-unsafe if
*                       wcsnps() is being used dynamically to alter its value.
*
*   ndpmax    int       The number of DPja or DQia keywords to allocate space
*                       for.  If set to -1, the value of the global variable
*                       NDPMAX will be used.  This is potentially
*                       thread-unsafe if disndp() is being used dynamically to
*                       alter its value.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err if enabled, see wcserr_enable().
*
*
* wcsauxi() - Default constructor for the auxprm struct
* -----------------------------------------------------
* wcsauxi() optionally allocates memory for an auxprm struct, attaches it to
* wcsprm, and sets all members of the struct to default values.
*
* Given:
*   alloc     int       If true, allocate memory unconditionally for the
*                       auxprm struct.
*
*                       If false, it is assumed that wcsprm::aux has already
*                       been set to point to an auxprm struct, in which case
*                       the user is responsible for managing that memory.
*                       However, if wcsprm::aux is a null pointer, memory will
*                       be allocated regardless.  (In other words, setting
*                       alloc true saves having to initalize the pointer to
*                       zero.)
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*
*
* wcssub() - Subimage extraction routine for the wcsprm struct
* ------------------------------------------------------------
* wcssub() extracts the coordinate description for a subimage from a wcsprm
* struct.  It does a deep copy, using wcsinit() to allocate memory for its
* arrays if required.  Only the "information to be provided" part of the
* struct is extracted.  Consequently, wcsset() need not have been, and won't
* be invoked on the struct from which the subimage is extracted.  A call to
* wcsset() is required to set up the subimage struct.
*
* The world coordinate system of the subimage must be separable in the sense
* that the world coordinates at any point in the subimage must depend only on
* the pixel coordinates of the axes extracted.  In practice, this means that
* the linear transformation matrix of the original image must not contain
* non-zero off-diagonal terms that associate any of the subimage axes with any
* of the non-subimage axes.  Likewise, if any distortions are associated with
* the subimage axes, they must not depend on any of the axes that are not
* being extracted.
*
* Note that while the required elements of the tabprm array are extracted, the
* wtbarr array is not.  (Thus it is not appropriate to call wcssub() after
* wcstab() but before filling the tabprm structs - refer to wcshdr.h.)
*
* wcssub() can also add axes to a wcsprm struct.  The new axes will be created
* using the defaults set by wcsinit() which produce a simple, unnamed, linear
* axis with world coordinate equal to the pixel coordinate.  These default
* values can be changed afterwards, before invoking wcsset().
*
* Given:
*   alloc     int       If true, allocate memory for the crpix, etc. arrays in
*                       the destination.  Otherwise, it is assumed that
*                       pointers to these arrays have been set by the user
*                       except if they are null pointers in which case memory
*                       will be allocated for them regardless.
*
*   wcssrc    const struct wcsprm*
*                       Struct to extract from.
*
* Given and returned:
*   nsub      int*
*   axes      int[]     Vector of length *nsub containing the image axis
*                       numbers (1-relative) to extract.  Order is
*                       significant; axes[0] is the axis number of the input
*                       image that corresponds to the first axis in the
*                       subimage, etc.
*
*                       Use an axis number of 0 to create a new axis using
*                       the defaults set by wcsinit().  They can be changed
*                       later.
*
*                       nsub (the pointer) may be set to zero, and so also may
*                       *nsub, which is interpreted to mean all axes in the
*                       input image; the number of axes will be returned if
*                       nsub != 0x0.  axes itself (the pointer) may be set to
*                       zero to indicate the first *nsub axes in their
*                       original order.
*
*                       Set both nsub (or *nsub) and axes to zero to do a deep
*                       copy of one wcsprm struct to another.
*
*                       Subimage extraction by coordinate axis type may be
*                       done by setting the elements of axes[] to the
*                       following special preprocessor macro values:
*
*                         WCSSUB_LONGITUDE: Celestial longitude.
*                         WCSSUB_LATITUDE:  Celestial latitude.
*                         WCSSUB_CUBEFACE:  Quadcube CUBEFACE axis.
*                         WCSSUB_SPECTRAL:  Spectral axis.
*                         WCSSUB_STOKES:    Stokes axis.
*                         WCSSUB_TIME:      Time axis.
*
*                       Refer to the notes (below) for further usage examples.
*
*                       On return, *nsub will be set to the number of axes in
*                       the subimage; this may be zero if there were no axes
*                       of the required type(s) (in which case no memory will
*                       be allocated).  axes[] will contain the axis numbers
*                       that were extracted, or 0 for newly created axes.  The
*                       vector length must be sufficient to contain all axis
*                       numbers.  No checks are performed to verify that the
*                       coordinate axes are consistent, this is done by
*                       wcsset().
*
*   wcsdst    struct wcsprm*
*                       Struct describing the subimage.  wcsprm::flag should
*                       be set to -1 if wcsdst was not previously initialized
*                       (memory leaks may result if it was previously
*                       initialized).
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                        12: Invalid subimage specification.
*                        13: Non-separable subimage coordinate system.
*
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err if enabled, see wcserr_enable().
*
* Notes:
*   1: Combinations of subimage axes of particular types may be extracted in
*      the same order as they occur in the input image by combining
*      preprocessor codes, for example
*
=        *nsub = 1;
=        axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
*
*      would extract the longitude, latitude, and spectral axes in the same
*      order as the input image.  If one of each were present, *nsub = 3 would
*      be returned.
*
*      For convenience, WCSSUB_CELESTIAL is defined as the combination
*      WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
*
*      The codes may also be negated to extract all but the types specified,
*      for example
*
=        *nsub = 4;
=        axes[0] = WCSSUB_LONGITUDE;
=        axes[1] = WCSSUB_LATITUDE;
=        axes[2] = WCSSUB_CUBEFACE;
=        axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
*
*      The last of these specifies all axis types other than spectral or
*      Stokes.  Extraction is done in the order specified by axes[] a
*      longitude axis (if present) would be extracted first (via axes[0]) and
*      not subsequently (via axes[3]).  Likewise for the latitude and cubeface
*      axes in this example.
*
*      From the foregoing, it is apparent that the value of *nsub returned may
*      be less than or greater than that given.  However, it will never exceed
*      the number of axes in the input image (plus the number of newly-created
*      axes if any were specified on input).
*
*
* wcscompare() - Compare two wcsprm structs for equality
* ------------------------------------------------------
* wcscompare() compares two wcsprm structs for equality.
*
* Given:
*   cmp       int       A bit field controlling the strictness of the
*                       comparison.  When 0, all fields must be identical.
*
*                       The following constants may be or'ed together to
*                       relax the comparison:
*                         WCSCOMPARE_ANCILLARY: Ignore ancillary keywords
*                           that don't change the WCS transformation, such
*                           as DATE-OBS or EQUINOX.
*                         WCSCOMPARE_TILING: Ignore integral differences in
*                           CRPIXja.  This is the 'tiling' condition, where
*                           two WCSes cover different regions of the same
*                           map projection and align on the same map grid.
*                         WCSCOMPARE_CRPIX: Ignore any differences at all in
*                           CRPIXja.  The two WCSes cover different regions
*                           of the same map projection but may not align on
*                           the same map grid.  Overrides WCSCOMPARE_TILING.
*
*   tol       double    Tolerance for comparison of floating-point values.
*                       For example, for tol == 1e-6, all floating-point
*                       values in the structs must be equal to the first 6
*                       decimal places.  A value of 0 implies exact equality.
*
*   wcs1      const struct wcsprm*
*                       The first wcsprm struct to compare.
*
*   wcs2      const struct wcsprm*
*                       The second wcsprm struct to compare.
*
* Returned:
*   equal     int*      Non-zero when the given structs are equal.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null pointer passed.
*
*
* wcscopy() macro - Copy routine for the wcsprm struct
* ----------------------------------------------------
* wcscopy() does a deep copy of one wcsprm struct to another.  As of
* WCSLIB 3.6, it is implemented as a preprocessor macro that invokes
* wcssub() with the nsub and axes pointers both set to zero.
*
*
* wcsfree() - Destructor for the wcsprm struct
* --------------------------------------------
* wcsfree() frees memory allocated for the wcsprm arrays by wcsinit() and/or
* wcsset().  wcsinit() records the memory it allocates and wcsfree() will only
* attempt to free this.
*
* PLEASE NOTE: wcsfree() must not be invoked on a wcsprm struct that was not
* initialized by wcsinit().
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcstrim() - Free unused arrays in the wcsprm struct
* ---------------------------------------------------
* wcstrim() frees memory allocated by wcsinit() for arrays in the wcsprm
* struct that remains unused after it has been set up by wcsset().
*
* The free'd array members are associated with FITS WCS keyrecords that are
* rarely used and usually just bloat the struct: wcsprm::crota, wcsprm::colax,
* wcsprm::cname, wcsprm::crder, wcsprm::csyer, wcsprm::czphs, and
* wcsprm::cperi.  If unused, wcsprm::pv, wcsprm::ps, and wcsprm::cd are also
* freed.
*
* Once these arrays have been freed, a test such as
=
=        if (!undefined(wcs->cname[i])) {...}
=
* must be protected as follows
=
=        if (wcs->cname && !undefined(wcs->cname[i])) {...}
=
* In addition, if wcsprm::npv is non-zero but less than wcsprm::npvmax, then
* the unused space in wcsprm::pv will be recovered (using realloc()).
* Likewise for wcsprm::ps.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                        14: wcsprm struct is unset.
*
*
* wcssize() - Compute the size of a wcsprm struct
* -----------------------------------------------
* wcssize() computes the full size of a wcsprm struct, including allocated
* memory.
*
* Given:
*   wcs       const struct wcsprm*
*                       Coordinate transformation parameters.
*
*                       If NULL, the base size of the struct and the allocated
*                       size are both set to zero.
*
* Returned:
*   sizes     int[2]    The first element is the base size of the struct as
*                       returned by sizeof(struct wcsprm).  The second element
*                       is the total allocated size, in bytes, assuming that
*                       the allocation was done by wcsini().  This figure
*                       includes memory allocated for members of constituent
*                       structs, such as wcsprm::lin.
*
*                       It is not an error for the struct not to have been set
*                       up via wcsset(), which normally results in additional
*                       memory allocation.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*
*
* auxsize() - Compute the size of a auxprm struct
* -----------------------------------------------
* auxsize() computes the full size of an auxprm struct, including allocated
* memory.
*
* Given:
*   aux       const struct auxprm*
*                       Auxiliary coordinate information.
*
*                       If NULL, the base size of the struct and the allocated
*                       size are both set to zero.
*
* Returned:
*   sizes     int[2]    The first element is the base size of the struct as
*                       returned by sizeof(struct auxprm).  The second element
*                       is the total allocated size, in bytes, currently zero.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*
*
* wcsenq() - enquire about the state of a wcsprm struct
* -----------------------------------------------------
* wcsenq() may be used to obtain information about the state of a wcsprm
* struct.  The function returns a true/false answer for the enquiry asked.
*
* Given:
*   wcs       const struct wcsprm*
*                       Coordinate transformation parameters.
*
*   enquiry   int       Enquiry according to the following parameters:
*                         WCSENQ_MEM: memory in the struct is being managed by
*                                     WCSLIB (see wcsini()).
*                         WCSENQ_SET: the struct has been set up by wcsset().
*                         WCSENQ_BYP: the struct is in bypass mode (see
*                                     wcsset()).
*                         WCSENQ_CHK: the struct is self-consistent in that
*                                     no changes have been made to any of the
*                                     "parameters to be given" since the last
*                                     call to wcsset().
*                       These may be combined by logical OR, e.g.
*                       WCSENQ_MEM | WCSENQ_SET.  The enquiry result will be
*                       the logical AND of the individual results.
*
* Function return value:
*             int       Enquiry result:
*                         0: False.
*                         1: True.
*
*
* wcsprt() - Print routine for the wcsprm struct
* ----------------------------------------------
* wcsprt() prints the contents of a wcsprm struct using wcsprintf().  Mainly
* intended for diagnostic purposes.
*
* Given:
*   wcs       const struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsperr() - Print error messages from a wcsprm struct
* -----------------------------------------------------
* wcsperr() prints the error message(s), if any, stored in a wcsprm struct,
* and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
* If there are no errors then nothing is printed.  It uses wcserr_prt(), q.v.
*
* Given:
*   wcs       const struct wcsprm*
*                       Coordinate transformation parameters.
*
*   prefix    const char *
*                       If non-NULL, each output line will be prefixed with
*                       this string.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsbchk() - Enable/disable bounds checking
* ------------------------------------------
* wcsbchk() is used to control bounds checking in the projection routines.
* Note that wcsset() always enables bounds checking.  wcsbchk() will invoke
* wcsset() on the wcsprm struct beforehand if necessary.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Given:
*   bounds    int       If bounds&1 then enable strict bounds checking for the
*                       spherical-to-Cartesian (s2x) transformation for the
*                       AZP, SZP, TAN, SIN, ZPN, and COP projections.
*
*                       If bounds&2 then enable strict bounds checking for the
*                       Cartesian-to-spherical (x2s) transformation for the
*                       HPX and XPH projections.
*
*                       If bounds&4 then enable bounds checking on the native
*                       coordinates returned by the Cartesian-to-spherical
*                       (x2s) transformations using prjchk().
*
*                       Zero it to disable all checking.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsset() - Setup routine for the wcsprm struct
* ----------------------------------------------
* wcsset() sets up a wcsprm struct according to information supplied within
* it (refer to the description of the wcsprm struct).
*
* wcsset() recognizes the NCP projection and converts it to the equivalent SIN
* projection and likewise translates GLS into SFL.  It also translates the
* AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.), possibly changing the
* input header keywords wcsprm::ctype and/or wcsprm::specsys if necessary.
*
* Note that this routine need not be called directly; it will be invoked by
* wcsp2s() and wcss2p() if the wcsprm::flag is anything other than a
* predefined magic value.
*
* wcsset() normally operates regardless of the value of wcsprm::flag; i.e.
* even if a struct was previously set up it will be reset unconditionally.
* However, a wcsprm struct may be put into "bypass" mode by invoking wcsset()
* initially with wcsprm::flag == 1 (rather than 0).  wcsset() will return
* immediately if invoked on a struct in that state.  To take a struct out of
* bypass mode, simply reset wcsprm::flag to zero.  See also wcsenq().
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         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: wcsset() always enables strict bounds checking in the projection
*      routines (via a call to prjini()).  Use wcsbchk() to modify
*      bounds-checking after wcsset() is invoked.
*
*
* wcsp2s() - Pixel-to-world transformation
* ----------------------------------------
* wcsp2s() transforms pixel coordinates to world coordinates.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Given:
*   ncoord,
*   nelem     int       The number of coordinates, each of vector length
*                       nelem but containing wcs.naxis coordinate elements.
*                       Thus nelem must equal or exceed the value of the
*                       NAXIS keyword unless ncoord == 1, in which case nelem
*                       is not used.
*
*   pixcrd    const double[ncoord][nelem]
*                       Array of pixel coordinates.
*
* Returned:
*   imgcrd    double[ncoord][nelem]
*                       Array of intermediate world coordinates.  For
*                       celestial axes, imgcrd[][wcs.lng] and
*                       imgcrd[][wcs.lat] are the projected x-, and
*                       y-coordinates in pseudo "degrees".  For spectral
*                       axes, imgcrd[][wcs.spec] is the intermediate spectral
*                       coordinate, in SI units.  For time axes,
*                       imgcrd[][wcs.time] is the intermediate time
*                       coordinate.
*
*   phi,theta double[ncoord]
*                       Longitude and latitude in the native coordinate system
*                       of the projection [deg].
*
*   world     double[ncoord][nelem]
*                       Array of world coordinates.  For celestial axes,
*                       world[][wcs.lng] and world[][wcs.lat] are the
*                       celestial longitude and latitude [deg].  For spectral
*                       axes, world[][wcs.spec] is the spectral coordinate, in
*                       SI units.  For time axes, world[][wcs.time] is the
*                       time coordinate.
*
*   stat      int[ncoord]
*                       Status return value for each coordinate:
*                         0: Success.
*                        1+: A bit mask indicating invalid pixel coordinate
*                            element(s).
*
* Function return value:
*             int       Status return value:
*                         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.
*                         8: One or more of the pixel coordinates were
*                            invalid, as indicated by the stat vector.
*
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err if enabled, see wcserr_enable().
*
*
* wcss2p() - World-to-pixel transformation
* ----------------------------------------
* wcss2p() transforms world coordinates to pixel coordinates.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Given:
*   ncoord,
*   nelem     int       The number of coordinates, each of vector length nelem
*                       but containing wcs.naxis coordinate elements.  Thus
*                       nelem must equal or exceed the value of the NAXIS
*                       keyword unless ncoord == 1, in which case nelem is not
*                       used.
*
*   world     const double[ncoord][nelem]
*                       Array of world coordinates.  For celestial axes,
*                       world[][wcs.lng] and world[][wcs.lat] are the
*                       celestial longitude and latitude [deg]. For spectral
*                       axes, world[][wcs.spec] is the spectral coordinate, in
*                       SI units.  For time axes, world[][wcs.time] is the
*                       time coordinate.
*
* Returned:
*   phi,theta double[ncoord]
*                       Longitude and latitude in the native coordinate
*                       system of the projection [deg].
*
*   imgcrd    double[ncoord][nelem]
*                       Array of intermediate world coordinates.  For
*                       celestial axes, imgcrd[][wcs.lng] and
*                       imgcrd[][wcs.lat] are the projected x-, and
*                       y-coordinates in pseudo "degrees".  For quadcube
*                       projections with a CUBEFACE axis the face number is
*                       also returned in imgcrd[][wcs.cubeface].  For
*                       spectral axes, imgcrd[][wcs.spec] is the intermediate
*                       spectral coordinate, in SI units.  For time axes,
*                       imgcrd[][wcs.time] is the intermediate time
*                       coordinate.
*
*   pixcrd    double[ncoord][nelem]
*                       Array of pixel coordinates.
*
*   stat      int[ncoord]
*                       Status return value for each coordinate:
*                         0: Success.
*                        1+: A bit mask indicating invalid world coordinate
*                            element(s).
*
* Function return value:
*             int       Status return value:
*                         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.
*                         9: One or more of the world coordinates were
*                            invalid, as indicated by the stat vector.
*
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err if enabled, see wcserr_enable().
*
*
* wcsmix() - Hybrid coordinate transformation
* -------------------------------------------
* wcsmix(), given either the celestial longitude or latitude plus an element
* of the pixel coordinate, solves for the remaining elements by iterating on
* the unknown celestial coordinate element using wcss2p().  Refer also to the
* notes below.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Indices for the celestial coordinates obtained
*                       by parsing the wcsprm::ctype[].
*
* Given:
*   mixpix    int       Which element of the pixel coordinate is given.
*
*   mixcel    int       Which element of the celestial coordinate is given:
*                         1: Celestial longitude is given in
*                            world[wcs.lng], latitude returned in
*                            world[wcs.lat].
*                         2: Celestial latitude is given in
*                            world[wcs.lat], longitude returned in
*                            world[wcs.lng].
*
*   vspan     const double[2]
*                       Solution interval for the celestial coordinate [deg].
*                       The ordering of the two limits is irrelevant.
*                       Longitude ranges may be specified with any convenient
*                       normalization, for example [-120,+120] is the same as
*                       [240,480], except that the solution will be returned
*                       with the same normalization, i.e. lie within the
*                       interval specified.
*
*   vstep     const double
*                       Step size for solution search [deg].  If zero, a
*                       sensible, although perhaps non-optimal default will be
*                       used.
*
*   viter     int       If a solution is not found then the step size will be
*                       halved and the search recommenced.  viter controls how
*                       many times the step size is halved.  The allowed range
*                       is 5 - 10.
*
* Given and returned:
*   world     double[naxis]
*                       World coordinate elements.  world[wcs.lng] and
*                       world[wcs.lat] are the celestial longitude and
*                       latitude [deg].  Which is given and which returned
*                       depends on the value of mixcel.  All other elements
*                       are given.
*
* Returned:
*   phi,theta double[naxis]
*                       Longitude and latitude in the native coordinate
*                       system of the projection [deg].
*
*   imgcrd    double[naxis]
*                       Image coordinate elements.  imgcrd[wcs.lng] and
*                       imgcrd[wcs.lat] are the projected x-, and
*                       y-coordinates in pseudo "degrees".
*
* Given and returned:
*   pixcrd    double[naxis]
*                       Pixel coordinate.  The element indicated by mixpix is
*                       given and the remaining elements are returned.
*
* Function return value:
*             int       Status return value:
*                         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.
*                        10: Invalid world coordinate.
*                        11: No solution found in the specified interval.
*
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err if enabled, see wcserr_enable().
*
* Notes:
*   1: Initially the specified solution interval is checked to see if it's a
*      "crossing" interval.  If it isn't, a search is made for a crossing
*      solution by iterating on the unknown celestial coordinate starting at
*      the upper limit of the solution interval and decrementing by the
*      specified step size.  A crossing is indicated if the trial value of the
*      pixel coordinate steps through the value specified.  If a crossing
*      interval is found then the solution is determined by a modified form of
*      "regula falsi" division of the crossing interval.  If no crossing
*      interval was found within the specified solution interval then a search
*      is made for a "non-crossing" solution as may arise from a point of
*      tangency.  The process is complicated by having to make allowance for
*      the discontinuities that occur in all map projections.
*
*      Once one solution has been determined others may be found by subsequent
*      invokations of wcsmix() with suitably restricted solution intervals.
*
*      Note the circumstance that arises when the solution point lies at a
*      native pole of a projection in which the pole is represented as a
*      finite curve, for example the zenithals and conics.  In such cases two
*      or more valid solutions may exist but wcsmix() only ever returns one.
*
*      Because of its generality wcsmix() is very compute-intensive.  For
*      compute-limited applications more efficient special-case solvers could
*      be written for simple projections, for example non-oblique cylindrical
*      projections.
*
*
* wcsccs() - Change celestial coordinate system
* ---------------------------------------------
* wcsccs() changes the celestial coordinate system of a wcsprm struct.  For
* example, from equatorial to galactic coordinates.
*
* Parameters that define the spherical coordinate transformation, essentially
* being three Euler angles, must be provided.  Thereby wcsccs() does not need
* prior knowledge of specific celestial coordinate systems.  It also has the
* advantage of making it completely general.
*
* Auxiliary members of the wcsprm struct relating to equatorial celestial
* coordinate systems may also be changed.
*
* Only orthodox spherical coordinate systems are supported.  That is, they
* must be right-handed, with latitude increasing from zero at the equator to
* +90 degrees at the pole.  This precludes systems such as aziumuth and zenith
* distance, which, however, could be handled as negative azimuth and
* elevation.
*
* PLEASE NOTE: Information in the wcsprm struct relating to the original
* coordinate system will be overwritten and therefore lost.  If this is
* undesirable, invoke wcsccs() on a copy of the struct made with wcssub().
* The wcsprm struct is reset on return with an explicit call to wcsset().
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.  Particular
*                       "values to be given" elements of the wcsprm struct
*                       are modified.
*
* Given:
*   lng2p1,
*   lat2p1    double    Longitude and latitude in the new celestial coordinate
*                       system of the pole (i.e. latitude +90) of the original
*                       system [deg].  See notes 1 and 2 below.
*
*   lng1p2    double    Longitude in the original celestial coordinate system
*                       of the pole (i.e. latitude +90) of the new system
*                       [deg].  See note 1 below.
*
*   clng,clat const char*
*                       Longitude and latitude identifiers of the new CTYPEia
*                       celestial axis codes, without trailing dashes.  For
*                       example, "RA" and "DEC" or "GLON" and "GLAT".  Up to
*                       four characters are used, longer strings need not be
*                       null-terminated.
*
*   radesys   const char*
*                       Used when transforming to equatorial coordinates,
*                       identified by clng == "RA" and clat = "DEC".  May be
*                       set to the null pointer to preserve the current value.
*                       Up to 71 characters are used, longer strings need not
*                       be null-terminated.
*
*                       If the new coordinate system is anything other than
*                       equatorial, then wcsprm::radesys will be cleared.
*
*   equinox   double    Used when transforming to equatorial coordinates.  May
*                       be set to zero to preserve the current value.
*
*                       If the new coordinate system is not equatorial, then
*                       wcsprm::equinox will be marked as undefined.
*
*   alt       const char*
*                       Character code for alternate coordinate descriptions
*                       (i.e. the 'a' in keyword names such as CTYPEia).  This
*                       is blank for the primary coordinate description, or
*                       one of the 26 upper-case letters, A-Z.  May be set to
*                       the null pointer, or null string if no change is
*                       required.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                        12: Invalid subimage specification (no celestial
*                            axes).
*
* Notes:
*   1: Follows the prescription given in WCS Paper II, Sect. 2.7 for changing
*      celestial coordinates.
*
*      The implementation takes account of indeterminacies that arise in that
*      prescription in the particular cases where one of the poles of the new
*      system is at the fiducial point, or one of them is at the native pole.
*
*   2: If lat2p1 == +90, i.e. where the poles of the two coordinate systems
*      coincide, then the spherical coordinate transformation becomes a simple
*      change in origin of longitude given by
*      lng2 = lng1 + (lng2p1 - lng1p2 - 180), and lat2 = lat1, where
*      (lng2,lat2) are coordinates in the new system, and (lng1,lat1) are
*      coordinates in the original system.
*
*      Likewise, if lat2p1 == -90, then lng2 = -lng1 + (lng2p1 + lng1p2), and
*      lat2 = -lat1.
*
*   3: For example, if the original coordinate system is B1950 equatorial and
*      the desired new coordinate system is galactic, then
*
*      - (lng2p1,lat2p1) are the galactic coordinates of the B1950 celestial
*        pole, defined by the IAU to be (123.0,+27.4), and lng1p2 is the B1950
*        right ascension of the galactic pole, defined as 192.25.  Clearly
*        these coordinates are fixed for a particular coordinate
*        transformation.
*
*      - (clng,clat) would be 'GLON' and 'GLAT', these being the FITS standard
*        identifiers for galactic coordinates.
*
*      - Since the new coordinate system is not equatorial, wcsprm::radesys
*        and wcsprm::equinox will be cleared.
*
*   4. The coordinates required for some common transformations (obtained from
*      https://ned.ipac.caltech.edu/coordinate_calculator) are as follows:
*
=      (123.0000,+27.4000) galactic coordinates of B1950 celestial pole,
=      (192.2500,+27.4000) B1950 equatorial coordinates of galactic pole.
*
=      (122.9319,+27.1283) galactic coordinates of J2000 celestial pole,
=      (192.8595,+27.1283) J2000 equatorial coordinates of galactic pole.
*
=      (359.6774,+89.7217) B1950 equatorial coordinates of J2000 pole,
=      (180.3162,+89.7217) J2000 equatorial coordinates of B1950 pole.
*
=      (270.0000,+66.5542) B1950 equatorial coordinates of B1950 ecliptic pole,
=      ( 90.0000,+66.5542) B1950 ecliptic coordinates of B1950 celestial pole.
*
=      (270.0000,+66.5607) J2000 equatorial coordinates of J2000 ecliptic pole,
=      ( 90.0000,+66.5607) J2000 ecliptic coordinates of J2000 celestial pole.
*
=      ( 26.7315,+15.6441) supergalactic coordinates of B1950 celestial pole,
=      (283.1894,+15.6441) B1950 equatorial coordinates of supergalactic pole.
*
=      ( 26.4505,+15.7089) supergalactic coordinates of J2000 celestial pole,
=      (283.7542,+15.7089) J2000 equatorial coordinates of supergalactic pole.
*
*
* wcssptr() - Spectral axis translation
* -------------------------------------
* wcssptr() translates the spectral axis in a wcsprm struct.  For example, a
* 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
*
* PLEASE NOTE: Information in the wcsprm struct relating to the original
* coordinate system will be overwritten and therefore lost.  If this is
* undesirable, invoke wcssptr() on a copy of the struct made with wcssub().
* The wcsprm struct is reset on return with an explicit call to wcsset().
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
*   i         int*      Index of the spectral axis (0-relative).  If given < 0
*                       it will be set to the first spectral axis identified
*                       from the ctype[] keyvalues in the wcsprm struct.
*
*   ctype     char[9]   Desired spectral CTYPEia.  Wildcarding may be used as
*                       for the ctypeS2 argument to spctrn() as described in
*                       the prologue of spc.h, i.e. if the final three
*                       characters are specified as "???", or if just the
*                       eighth character is specified as '?', the correct
*                       algorithm code will be substituted and returned.
*
* Function return value:
*             int       Status return value:
*                         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.
*                        12: Invalid subimage specification (no spectral
*                            axis).
*
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err if enabled, see wcserr_enable().
*
*
* wcslib_version() - WCSLIB version number
* ----------------------------------------
* wcslib_version() returns the WCSLIB version number.
*
* The major version number changes when the ABI changes or when the license
* conditions change.  ABI changes typically result from a change to the
* contents of one of the structs.  The major version number is used to
* distinguish between incompatible versions of the sharable library.
*
* The minor version number changes with new functionality or bug fixes that do
* not involve a change in the ABI.
*
* The auxiliary version number (which is often absent) signals changes to the
* documentation, test suite, build procedures, or any other change that does
* not affect the compiled library.
*
* Returned:
*   vers[3]   int[3]    The broken-down version number:
*                         0: Major version number.
*                         1: Minor version number.
*                         2: Auxiliary version number (zero if absent).
*                       May be given as a null pointer if not required.
*
* Function return value:
*             char*     A null-terminated, statically allocated string
*                       containing the version number in the usual form, i.e.
*                       "<major>.<minor>.<auxiliary>".
*
*
* wcsprm struct - Coordinate transformation parameters
* ----------------------------------------------------
* The wcsprm struct contains information required to transform world
* coordinates.  It consists of certain members that must be set by the user
* ("given") and others that are set by the WCSLIB routines ("returned").
* While the addresses of the arrays themselves may be set by wcsinit() if it
* (optionally) allocates memory, their contents must be set by the user.
*
* Some parameters that are given are not actually required for transforming
* coordinates.  These are described as "auxiliary"; the struct simply provides
* a place to store them, though they may be used by wcshdo() in constructing a
* FITS header from a wcsprm struct.  Some of the returned values are supplied
* for informational purposes and others are for internal use only as
* indicated.
*
* In practice, it is expected that a WCS parser would scan the FITS header to
* determine the number of coordinate axes.  It would then use wcsinit() to
* allocate memory for arrays in the wcsprm struct and set default values.
* Then as it reread the header and identified each WCS keyrecord it would load
* the value into the relevant wcsprm array element.  This is essentially what
* wcspih() does - refer to the prologue of wcshdr.h.  As the final step,
* wcsset() is invoked, either directly or indirectly, to set the derived
* members of the wcsprm struct.  wcsset() strips off trailing blanks in all
* string members and null-fills the character array.
*
*   int flag
*     (Given and returned) This flag must be set to zero (or 1, see wcsset())
*     whenever any of the following wcsprm members are set or changed:
*
*       - wcsprm::naxis (q.v., not normally set by the user),
*       - wcsprm::crpix,
*       - wcsprm::pc,
*       - wcsprm::cdelt,
*       - wcsprm::crval,
*       - wcsprm::cunit,
*       - wcsprm::ctype,
*       - wcsprm::lonpole,
*       - wcsprm::latpole,
*       - wcsprm::restfrq,
*       - wcsprm::restwav,
*       - wcsprm::npv,
*       - wcsprm::pv,
*       - wcsprm::nps,
*       - wcsprm::ps,
*       - wcsprm::cd,
*       - wcsprm::crota,
*       - wcsprm::altlin,
*       - wcsprm::ntab,
*       - wcsprm::nwtb,
*       - wcsprm::tab,
*       - wcsprm::wtb.
*
*     This signals the initialization routine, wcsset(), to recompute the
*     returned members of the linprm, celprm, spcprm, and tabprm structs.
*     wcsset() will reset flag to indicate that this has been done.
*
*     PLEASE NOTE: flag should be set to -1 when wcsinit() is called for the
*     first time for a particular wcsprm struct in order to initialize memory
*     management.  It must ONLY be used on the first initialization otherwise
*     memory leaks may result.
*
*   int naxis
*     (Given or returned) Number of pixel and world coordinate elements.
*
*     If wcsinit() is used to initialize the linprm struct (as would normally
*     be the case) then it will set naxis from the value passed to it as a
*     function argument.  The user should not subsequently modify it.
*
*   double *crpix
*     (Given) Address of the first element of an array of double containing
*     the coordinate reference pixel, CRPIXja.
*
*   double *pc
*     (Given) Address of the first element of the PCi_ja (pixel coordinate)
*     transformation matrix.  The expected order is
*
=       struct wcsprm wcs;
=       wcs.pc = {PC1_1, PC1_2, PC2_1, PC2_2};
*
*     This may be constructed conveniently from a 2-D array via
*
=       double m[2][2] = {{PC1_1, PC1_2},
=                         {PC2_1, PC2_2}};
*
*     which is equivalent to
*
=       double m[2][2];
=       m[0][0] = PC1_1;
=       m[0][1] = PC1_2;
=       m[1][0] = PC2_1;
=       m[1][1] = PC2_2;
*
*     The storage order for this 2-D array is the same as for the 1-D array,
*     whence
*
=       wcs.pc = *m;
*
*     would be legitimate.
*
*   double *cdelt
*     (Given) Address of the first element of an array of double containing
*     the coordinate increments, CDELTia.
*
*   double *crval
*     (Given) Address of the first element of an array of double containing
*     the coordinate reference values, CRVALia.
*
*   char (*cunit)[72]
*     (Given) Address of the first element of an array of char[72] containing
*     the CUNITia keyvalues which define the units of measurement of the
*     CRVALia, CDELTia, and CDi_ja keywords.
*
*     As CUNITia is an optional header keyword, cunit[][72] may be left blank
*     but otherwise is expected to contain a standard units specification as
*     defined by WCS Paper I.  Utility function wcsutrn(), described in
*     wcsunits.h, is available to translate commonly used non-standard units
*     specifications but this must be done as a separate step before invoking
*     wcsset().
*
*     For celestial axes, if cunit[][72] is not blank, wcsset() uses
*     wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to
*     degrees.  It then resets cunit[][72] to "deg".
*
*     For spectral axes, if cunit[][72] is not blank, wcsset() uses wcsunits()
*     to parse it and scale cdelt[], crval[], and cd[][*] to SI units.  It
*     then resets cunit[][72] accordingly.
*
*     wcsset() ignores cunit[][72] for other coordinate types; cunit[][72] may
*     be used to label coordinate values.
*
*     These variables accomodate the longest allowed string-valued FITS
*     keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*   char (*ctype)[72]
*     (Given) Address of the first element of an array of char[72] containing
*     the coordinate axis types, CTYPEia.
*
*     The ctype[][72] keyword values must be in upper case and there must be
*     zero or one pair of matched celestial axis types, and zero or one
*     spectral axis.  The ctype[][72] strings should be padded with blanks on
*     the right and null-terminated so that they are at least eight characters
*     in length.
*
*     These variables accomodate the longest allowed string-valued FITS
*     keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*   double lonpole
*     (Given and returned) The native longitude of the celestial pole, phi_p,
*     given by LONPOLEa [deg] or by PVi_2a [deg] attached to the longitude
*     axis which takes precedence if defined, and ...
*   double latpole
*     (Given and returned) ... the native latitude of the celestial pole,
*     theta_p, given by LATPOLEa [deg] or by PVi_3a [deg] attached to the
*     longitude axis which takes precedence if defined.
*
*     lonpole and latpole may be left to default to values set by wcsinit()
*     (see celprm::ref), but in any case they will be reset by wcsset() to
*     the values actually used.  Note therefore that if the wcsprm struct is
*     reused without resetting them, whether directly or via wcsinit(), they
*     will no longer have their default values.
*
*   double restfrq
*     (Given) The rest frequency [Hz], and/or ...
*   double restwav
*     (Given) ... the rest wavelength in vacuo [m], only one of which need be
*     given, the other should be set to zero.
*
*   int npv
*     (Given) The number of entries in the wcsprm::pv[] array.
*
*   int npvmax
*     (Given or returned) The length of the wcsprm::pv[] array.
*
*     npvmax will be set by wcsinit() if it allocates memory for wcsprm::pv[],
*     otherwise it must be set by the user.  See also wcsnpv().
*
*   struct pvcard *pv
*     (Given) Address of the first element of an array of length npvmax of
*     pvcard structs.
*
*     As a FITS header parser encounters each PVi_ma keyword it should load it
*     into a pvcard struct in the array and increment npv.  wcsset()
*     interprets these as required.
*
*     Note that, if they were not given, wcsset() resets the entries for
*     PVi_1a, PVi_2a, PVi_3a, and PVi_4a for longitude axis i to match
*     phi_0 and theta_0 (the native longitude and latitude of the reference
*     point), LONPOLEa and LATPOLEa respectively.
*
*   int nps
*     (Given) The number of entries in the wcsprm::ps[] array.
*
*   int npsmax
*     (Given or returned) The length of the wcsprm::ps[] array.
*
*     npsmax will be set by wcsinit() if it allocates memory for wcsprm::ps[],
*     otherwise it must be set by the user.  See also wcsnps().
*
*   struct pscard *ps
*     (Given) Address of the first element of an array of length npsmax of
*     pscard structs.
*
*     As a FITS header parser encounters each PSi_ma keyword it should load it
*     into a pscard struct in the array and increment nps.  wcsset()
*     interprets these as required (currently no PSi_ma keyvalues are
*     recognized).
*
*   double *cd
*     (Given) For historical compatibility, the wcsprm struct supports two
*     alternate specifications of the linear transformation matrix, those
*     associated with the CDi_ja keywords, and ...
*   double *crota
*     (Given) ... those associated with the CROTAi keywords.  Although these
*     may not formally co-exist with PCi_ja, the approach taken here is simply
*     to ignore them if given in conjunction with PCi_ja.
*
*   int altlin
*     (Given) altlin is a bit flag that denotes which of the PCi_ja, CDi_ja
*     and CROTAi keywords are present in the header:
*
*     - Bit 0: PCi_ja is present.
*
*     - Bit 1: CDi_ja is present.
*
*       Matrix elements in the IRAF convention are equivalent to the product
*       CDi_ja = CDELTia * PCi_ja, but the defaults differ from that of the
*       PCi_ja matrix.  If one or more CDi_ja keywords are present then all
*       unspecified CDi_ja default to zero.  If no CDi_ja (or CROTAi) keywords
*       are present, then the header is assumed to be in PCi_ja form whether
*       or not any PCi_ja keywords are present since this results in an
*       interpretation of CDELTia consistent with the original FITS
*       specification.
*
*       While CDi_ja may not formally co-exist with PCi_ja, it may co-exist
*       with CDELTia and CROTAi which are to be ignored.
*
*     - Bit 2: CROTAi is present.
*
*       In the AIPS convention, CROTAi may only be associated with the
*       latitude axis of a celestial axis pair.  It specifies a rotation in
*       the image plane that is applied AFTER the CDELTia; any other CROTAi
*       keywords are ignored.
*
*       CROTAi may not formally co-exist with PCi_ja.
*
*       CROTAi and CDELTia may formally co-exist with CDi_ja but if so are to
*       be ignored.
*
*     - Bit 3: PCi_ja + CDELTia was derived from CDi_ja by wcspcx().
*
*       This bit is set by wcspcx() when it derives PCi_ja and CDELTia from
*       CDi_ja via an orthonormal decomposition.  In particular, it signals
*       wcsset() not to replace PCi_ja by a copy of CDi_ja with CDELTia set
*       to unity.
*
*     CDi_ja and CROTAi keywords, if found, are to be stored in the wcsprm::cd
*     and wcsprm::crota arrays which are dimensioned similarly to wcsprm::pc
*     and wcsprm::cdelt.  FITS header parsers should use the following
*     procedure:
*
*     - Whenever a PCi_ja keyword is encountered: altlin |= 1;
*
*     - Whenever a CDi_ja keyword is encountered: altlin |= 2;
*
*     - Whenever a CROTAi keyword is encountered: altlin |= 4;
*
*     If none of these bits are set the PCi_ja representation results, i.e.
*     wcsprm::pc and wcsprm::cdelt will be used as given.
*
*     These alternate specifications of the linear transformation matrix are
*     translated immediately to PCi_ja by wcsset() and are invisible to the
*     lower-level WCSLIB routines.  In particular, unless bit 3 is also set,
*     wcsset() resets wcsprm::cdelt to unity if CDi_ja is present (and no
*     PCi_ja).
*
*     If CROTAi are present but none is associated with the latitude axis
*     (and no PCi_ja or CDi_ja), then wcsset() reverts to a unity PCi_ja
*     matrix.
*
*   int velref
*     (Given) AIPS velocity code VELREF, refer to spcaips().
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::velref is changed.
*
*   char alt[4]
*     (Given, auxiliary) Character code for alternate coordinate descriptions
*     (i.e. the 'a' in keyword names such as CTYPEia).  This is blank for the
*     primary coordinate description, or one of the 26 upper-case letters,
*     A-Z.
*
*     An array of four characters is provided for alignment purposes, only the
*     first is used.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::alt is changed.
*
*   int colnum
*     (Given, auxiliary) Where the coordinate representation is associated
*     with an image-array column in a FITS binary table, this variable may be
*     used to record the relevant column number.
*
*     It should be set to zero for an image header or pixel list.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::colnum is changed.
*
*   int *colax
*     (Given, auxiliary) Address of the first element of an array of int
*     recording the column numbers for each axis in a pixel list.
*
*     The array elements should be set to zero for an image header or image
*     array in a binary table.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::colax is changed.
*
*   char (*cname)[72]
*     (Given, auxiliary) The address of the first element of an array of
*     char[72] containing the coordinate axis names, CNAMEia.
*
*     These variables accomodate the longest allowed string-valued FITS
*     keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::cname is changed.
*
*   double *crder
*     (Given, auxiliary) Address of the first element of an array of double
*     recording the random error in the coordinate value, CRDERia.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::crder is changed.
*
*   double *csyer
*     (Given, auxiliary) Address of the first element of an array of double
*     recording the systematic error in the coordinate value, CSYERia.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::csyer is changed.
*
*   double *czphs
*     (Given, auxiliary) Address of the first element of an array of double
*     recording the time at the zero point of a phase axis, CZPHSia.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::czphs is changed.
*
*   double *cperi
*     (Given, auxiliary) Address of the first element of an array of double
*     recording the period of a phase axis, CPERIia.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::cperi is changed.
*
*   char wcsname[72]
*     (Given, auxiliary) The name given to the coordinate representation,
*     WCSNAMEa.  This variable accomodates the longest allowed string-valued
*     FITS keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::wcsname is changed.
*
*   char timesys[72]
*     (Given, auxiliary) TIMESYS keyvalue, being the time scale (UTC, TAI,
*     etc.) in which all other time-related auxiliary header values are
*     recorded.  Also defines the time scale for an image axis with CTYPEia
*     set to 'TIME'.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timesys is changed.
*
*   char trefpos[72]
*     (Given, auxiliary) TREFPOS keyvalue, being the location in space where
*     the recorded time is valid.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::trefpos is changed.
*
*   char trefdir[72]
*     (Given, auxiliary) TREFDIR keyvalue, being the reference direction used
*     in calculating a pathlength delay.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::trefdir is changed.
*
*   char plephem[72]
*     (Given, auxiliary) PLEPHEM keyvalue, being the Solar System ephemeris
*     used for calculating a pathlength delay.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::plephem is changed.
*
*   char timeunit[72]
*     (Given, auxiliary) TIMEUNIT keyvalue, being the time units in which
*     the following header values are expressed: TSTART, TSTOP, TIMEOFFS,
*     TIMSYER, TIMRDER, TIMEDEL.  It also provides the default value for
*     CUNITia for time axes.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timeunit is changed.
*
*   char dateref[72]
*     (Given, auxiliary) DATEREF keyvalue, being the date of a reference epoch
*     relative to which other time measurements refer.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::dateref is changed.
*
*   double mjdref[2]
*     (Given, auxiliary) MJDREF keyvalue, equivalent to DATEREF expressed as
*     a Modified Julian Date (MJD = JD - 2400000.5).  The value is given as
*     the sum of the two-element vector, allowing increased precision.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdref is changed.
*
*   double timeoffs
*     (Given, auxiliary) TIMEOFFS keyvalue, being a time offset, which may be
*     used, for example, to provide a uniform clock correction for times
*     referenced to DATEREF.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timeoffs is changed.
*
*   char dateobs[72]
*     (Given, auxiliary) DATE-OBS keyvalue, being the date at the start of the
*     observation unless otherwise explained in the DATE-OBS keycomment, in
*     ISO format, yyyy-mm-ddThh:mm:ss.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::dateobs is changed.
*
*   char datebeg[72]
*     (Given, auxiliary) DATE-BEG keyvalue, being the date at the start of the
*     observation in ISO format, yyyy-mm-ddThh:mm:ss.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::datebeg is changed.
*
*   char dateavg[72]
*     (Given, auxiliary) DATE-AVG keyvalue, being the date at a representative
*     mid-point of the observation in ISO format, yyyy-mm-ddThh:mm:ss.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::dateavg is changed.
*
*   char dateend[72]
*     (Given, auxiliary) DATE-END keyvalue, baing the date at the end of the
*     observation in ISO format, yyyy-mm-ddThh:mm:ss.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::dateend is changed.
*
*   double mjdobs
*     (Given, auxiliary) MJD-OBS keyvalue, equivalent to DATE-OBS expressed
*     as a Modified Julian Date (MJD = JD - 2400000.5).
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdobs is changed.
*
*   double mjdbeg
*     (Given, auxiliary) MJD-BEG keyvalue, equivalent to DATE-BEG expressed
*     as a Modified Julian Date (MJD = JD - 2400000.5).
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdbeg is changed.
*
*   double mjdavg
*     (Given, auxiliary) MJD-AVG keyvalue, equivalent to DATE-AVG expressed
*     as a Modified Julian Date (MJD = JD - 2400000.5).
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdavg is changed.
*
*   double mjdend
*     (Given, auxiliary) MJD-END keyvalue, equivalent to DATE-END expressed
*     as a Modified Julian Date (MJD = JD - 2400000.5).
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdend is changed.
*
*   double jepoch
*     (Given, auxiliary) JEPOCH keyvalue, equivalent to DATE-OBS expressed
*     as a Julian epoch.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::jepoch is changed.
*
*   double bepoch
*     (Given, auxiliary) BEPOCH keyvalue, equivalent to DATE-OBS expressed
*     as a Besselian epoch
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::bepoch is changed.
*
*   double tstart
*     (Given, auxiliary) TSTART keyvalue, equivalent to DATE-BEG expressed
*     as a time in units of TIMEUNIT relative to DATEREF+TIMEOFFS.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::tstart is changed.
*
*   double tstop
*     (Given, auxiliary) TSTOP keyvalue, equivalent to DATE-END expressed
*     as a time in units of TIMEUNIT relative to DATEREF+TIMEOFFS.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::tstop is changed.
*
*   double xposure
*     (Given, auxiliary) XPOSURE keyvalue, being the effective exposure time
*     in units of TIMEUNIT.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::xposure is changed.
*
*   double telapse
*     (Given, auxiliary) TELAPSE keyvalue, equivalent to the elapsed time
*     between DATE-BEG and DATE-END, in units of TIMEUNIT.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::telapse is changed.
*
*   double timsyer
*     (Given, auxiliary) TIMSYER keyvalue, being the absolute error of the
*     time values, in units of TIMEUNIT.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timsyer is changed.
*
*   double timrder
*     (Given, auxiliary) TIMRDER keyvalue, being the accuracy of time stamps
*     relative to each other, in units of TIMEUNIT.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timrder is changed.
*
*   double timedel
*     (Given, auxiliary) TIMEDEL keyvalue, being the resolution of the time
*     stamps.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timedel is changed.
*
*   double timepixr
*     (Given, auxiliary) TIMEPIXR keyvalue, being the relative position of the
*     time stamps in binned time intervals, a value between 0.0 and 1.0.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timepixr is changed.
*
*   double obsgeo[6]
*     (Given, auxiliary) Location of the observer in a standard terrestrial
*     reference frame.  The first three give ITRS Cartesian coordinates
*     OBSGEO-X [m],   OBSGEO-Y [m],   OBSGEO-Z [m], and the second three give
*     OBSGEO-L [deg], OBSGEO-B [deg], OBSGEO-H [m], which are related through
*     a standard transformation.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::obsgeo is changed.
*
*   char obsorbit[72]
*     (Given, auxiliary) OBSORBIT keyvalue, being the URI, URL, or name of an
*     orbit ephemeris file giving spacecraft coordinates relating to TREFPOS.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::obsorbit is changed.
*
*   char radesys[72]
*     (Given, auxiliary) The equatorial or ecliptic coordinate system type,
*     RADESYSa.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::radesys is changed.
*
*   double equinox
*     (Given, auxiliary) The equinox associated with dynamical equatorial or
*     ecliptic coordinate systems, EQUINOXa (or EPOCH in older headers).  Not
*     applicable to ICRS equatorial or ecliptic coordinates.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::equinox is changed.
*
*   char specsys[72]
*     (Given, auxiliary) Spectral reference frame (standard of rest),
*     SPECSYSa.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::specsys is changed.
*
*   char ssysobs[72]
*     (Given, auxiliary) The spectral reference frame in which there is no
*     differential variation in the spectral coordinate across the
*     field-of-view, SSYSOBSa.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::ssysobs is changed.
*
*   double velosys
*     (Given, auxiliary) The relative radial velocity [m/s] between the
*     observer and the selected standard of rest in the direction of the
*     celestial reference coordinate, VELOSYSa.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::velosys is changed.
*
*   double zsource
*     (Given, auxiliary) The redshift, ZSOURCEa, of the source.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::zsource is changed.
*
*   char ssyssrc[72]
*     (Given, auxiliary) The spectral reference frame (standard of rest),
*     SSYSSRCa, in which wcsprm::zsource was measured.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::ssyssrc is changed.
*
*   double velangl
*     (Given, auxiliary) The angle [deg] that should be used to decompose an
*     observed velocity into radial and transverse components.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::velangl is changed.
*
*   struct auxprm *aux
*     (Given, auxiliary) This struct holds auxiliary coordinate system
*     information of a specialist nature.  While these parameters may be
*     widely recognized within particular fields of astronomy, they differ
*     from the above auxiliary parameters in not being defined by any of the
*     FITS WCS standards.  Collecting them together in a separate struct that
*     is allocated only when required helps to control bloat in the size of
*     the wcsprm struct.
*
*   int ntab
*     (Given) See wcsprm::tab.
*
*   int nwtb
*     (Given) See wcsprm::wtb.
*
*   struct tabprm *tab
*     (Given) Address of the first element of an array of ntab tabprm structs
*     for which memory has been allocated.  These are used to store tabular
*     transformation parameters.
*
*     Although technically wcsprm::ntab and tab are "given", they will
*     normally be set by invoking wcstab(), whether directly or indirectly.
*
*     The tabprm structs contain some members that must be supplied and others
*     that are derived.  The information to be supplied comes primarily from
*     arrays stored in one or more FITS binary table extensions.  These
*     arrays, referred to here as "wcstab arrays", are themselves located by
*     parameters stored in the FITS image header.
*
*   struct wtbarr *wtb
*     (Given) Address of the first element of an array of nwtb wtbarr structs
*     for which memory has been allocated.  These are used in extracting
*     wcstab arrays from a FITS binary table.
*
*     Although technically wcsprm::nwtb and wtb are "given", they will
*     normally be set by invoking wcstab(), whether directly or indirectly.
*
*   char lngtyp[8]
*     (Returned) Four-character WCS celestial longitude and ...
*   char lattyp[8]
*     (Returned) ... latitude axis types. e.g. "RA", "DEC", "GLON", "GLAT",
*     etc. extracted from 'RA--', 'DEC-', 'GLON', 'GLAT', etc. in the first
*     four characters of CTYPEia but with trailing dashes removed.  (Declared
*     as char[8] for alignment reasons.)
*
*   int lng
*     (Returned) Index for the longitude coordinate, and ...
*   int lat
*     (Returned) ... index for the latitude coordinate, and ...
*   int spec
*     (Returned) ... index for the spectral coordinate, and ...
*   int time
*     (Returned) ... index for the time coordinate in the imgcrd[][] and
*     world[][] arrays in the API of wcsp2s(), wcss2p() and wcsmix().
*
*     These may also serve as indices into the pixcrd[][] array provided that
*     the PCi_ja matrix does not transpose axes.
*
*   int cubeface
*     (Returned) Index into the pixcrd[][] array for the CUBEFACE axis.  This
*     is used for quadcube projections where the cube faces are stored on a
*     separate axis (see wcs.h).
*
*   int chksum
*     (Returned) Checksum of keyvalues provided (see wcsprm::flag).  Used by
*     wcsenq() to validate the self-consistency of the struct.  Note that
*     the checksum incorporates addresses and is therefore highly specific to
*     the instance of the wcsprm struct.
*
*   int *types
*     (Returned) Address of the first element of an array of int containing a
*     four-digit type code for each axis.
*
*     - First digit (i.e. 1000s):
*       - 0: Non-specific coordinate type.
*       - 1: Stokes coordinate.
*       - 2: Celestial coordinate (including CUBEFACE).
*       - 3: Spectral coordinate.
*       - 4: Time coordinate.
*
*     - Second digit (i.e. 100s):
*       - 0: Linear axis.
*       - 1: Quantized axis (STOKES, CUBEFACE).
*       - 2: Non-linear celestial axis.
*       - 3: Non-linear spectral axis.
*       - 4: Logarithmic axis.
*       - 5: Tabular axis.
*
*     - Third digit (i.e. 10s):
*       - 0: Group number, e.g. lookup table number, being an index into the
*            tabprm array (see above).
*
*     - The fourth digit is used as a qualifier depending on the axis type.
*
*       - For celestial axes:
*         - 0: Longitude coordinate.
*         - 1: Latitude coordinate.
*         - 2: CUBEFACE number.
*
*       - For lookup tables: the axis number in a multidimensional table.
*
*     CTYPEia in "4-3" form with unrecognized algorithm code will have its
*     type set to -1 and generate an error.
*
*   struct linprm lin
*     (Returned) Linear transformation parameters (usage is described in the
*     prologue to lin.h).
*
*   struct celprm cel
*     (Returned) Celestial transformation parameters (usage is described in
*     the prologue to cel.h).
*
*   struct spcprm spc
*     (Returned) Spectral transformation parameters (usage is described in the
*     prologue to spc.h).
*
*   struct wcserr *err
*     (Returned) If enabled, when an error status is returned, this struct
*     contains detailed information about the error, see wcserr_enable().
*
*   int m_flag
*     (For internal use only.)
*   int m_naxis
*     (For internal use only.)
*   double *m_crpix
*     (For internal use only.)
*   double *m_pc
*     (For internal use only.)
*   double *m_cdelt
*     (For internal use only.)
*   double *m_crval
*     (For internal use only.)
*   char (*m_cunit)[72]
*     (For internal use only.)
*   char (*m_ctype)[72]
*     (For internal use only.)
*   struct pvcard *m_pv
*     (For internal use only.)
*   struct pscard *m_ps
*     (For internal use only.)
*   double *m_cd
*     (For internal use only.)
*   double *m_crota
*     (For internal use only.)
*   int *m_colax
*     (For internal use only.)
*   char (*m_cname)[72]
*     (For internal use only.)
*   double *m_crder
*     (For internal use only.)
*   double *m_csyer
*     (For internal use only.)
*   double *m_czphs
*     (For internal use only.)
*   double *m_cperi
*     (For internal use only.)
*   struct tabprm *m_tab
*     (For internal use only.)
*   struct wtbarr *m_wtb
*     (For internal use only.)
*
*
* pvcard struct - Store for PVi_ma keyrecords
* -------------------------------------------
* The pvcard struct is used to pass the parsed contents of PVi_ma keyrecords
* to wcsset() via the wcsprm struct.
*
* All members of this struct are to be set by the user.
*
*   int i
*     (Given) Axis number (1-relative), as in the FITS PVi_ma keyword.  If
*     i == 0, wcsset() will replace it with the latitude axis number.
*
*   int m
*     (Given) Parameter number (non-negative), as in the FITS PVi_ma keyword.
*
*   double value
*     (Given) Parameter value.
*
*
* pscard struct - Store for PSi_ma keyrecords
* -------------------------------------------
* The pscard struct is used to pass the parsed contents of PSi_ma keyrecords
* to wcsset() via the wcsprm struct.
*
* All members of this struct are to be set by the user.
*
*   int i
*     (Given) Axis number (1-relative), as in the FITS PSi_ma keyword.
*
*   int m
*     (Given) Parameter number (non-negative), as in the FITS PSi_ma keyword.
*
*   char value[72]
*     (Given) Parameter value.
*
*
* auxprm struct - Additional auxiliary parameters
* -----------------------------------------------
* The auxprm struct holds auxiliary coordinate system information of a
* specialist nature.  It is anticipated that this struct will expand in future
* to accomodate additional parameters.
*
* All members of this struct are to be set by the user.
*
*   double rsun_ref
*     (Given, auxiliary) Reference radius of the Sun used in coordinate
*     calculations (m).
*
*   double dsun_obs
*     (Given, auxiliary) Distance between the centre of the Sun and the
*     observer (m).
*
*   double crln_obs
*     (Given, auxiliary) Carrington heliographic longitude of the observer
*     (deg).
*
*   double hgln_obs
*     (Given, auxiliary) Stonyhurst heliographic longitude of the observer
*     (deg).
*
*   double hglt_obs
*     (Given, auxiliary) Heliographic latitude (Carrington or Stonyhurst) of
*     the observer (deg).
*
*   double a_radius
*     Length of the semi-major axis of a triaxial ellipsoid approximating the
*     shape of a body (e.g. planet) in the solar system (m).
*
*   double b_radius
*     Length of the intermediate axis, normal to the semi-major and semi-minor
*     axes, of a triaxial ellipsoid approximating the shape of a body (m).
*
*   double c_radius
*     Length of the semi-minor axis, normal to the semi-major axis, of a
*     triaxial ellipsoid approximating the shape of a body (m).
*
*   double blon_obs
*     Bodycentric longitude of the observer in the coordinate system fixed to
*     the planet or other solar system body (deg, in range 0 to 360).
*
*   double blat_obs
*     Bodycentric latitude of the observer in the coordinate system fixed to
*     the planet or other solar system body (deg).
*
*   double bdis_obs
*     Bodycentric distance of the observer (m).
*
*
* Global variable: const char *wcs_errmsg[] - Status return messages
* ------------------------------------------------------------------
* Error messages to match the status value returned from each function.
*
*===========================================================================*/

#ifndef WCSLIB_WCS
#define WCSLIB_WCS

#include "lin.h"
#include "cel.h"
#include "spc.h"

#ifdef __cplusplus
extern "C" {
#define wtbarr wtbarr_s		// See prologue of wtbarr.h.
#endif

enum wcsenq_enum {
  WCSENQ_MEM = 1,		// wcsprm struct memory is managed by WCSLIB.
  WCSENQ_SET = 2,		// wcsprm struct has been set up.
  WCSENQ_BYP = 4,		// wcsprm struct is in bypass mode.
  WCSENQ_CHK = 8,		// wcsprm struct is self-consistent.
};

#define WCSSUB_LONGITUDE 0x1001
#define WCSSUB_LATITUDE  0x1002
#define WCSSUB_CUBEFACE  0x1004
#define WCSSUB_CELESTIAL 0x1007
#define WCSSUB_SPECTRAL  0x1008
#define WCSSUB_STOKES    0x1010
#define WCSSUB_TIME      0x1020


#define WCSCOMPARE_ANCILLARY 0x0001
#define WCSCOMPARE_TILING    0x0002
#define WCSCOMPARE_CRPIX     0x0004


extern const char *wcs_errmsg[];

enum wcs_errmsg_enum {
  WCSERR_SUCCESS         =  0,	// Success.
  WCSERR_NULL_POINTER    =  1,	// Null wcsprm pointer passed.
  WCSERR_MEMORY          =  2,	// Memory allocation failed.
  WCSERR_SINGULAR_MTX    =  3,	// Linear transformation matrix is singular.
  WCSERR_BAD_CTYPE       =  4,	// Inconsistent or unrecognized coordinate
				// axis type.
  WCSERR_BAD_PARAM       =  5,	// Invalid parameter value.
  WCSERR_BAD_COORD_TRANS =  6,	// Unrecognized coordinate transformation
				// parameter.
  WCSERR_ILL_COORD_TRANS =  7,	// Ill-conditioned coordinate transformation
				// parameter.
  WCSERR_BAD_PIX         =  8,	// One or more of the pixel coordinates were
				// invalid.
  WCSERR_BAD_WORLD       =  9,	// One or more of the world coordinates were
				// invalid.
  WCSERR_BAD_WORLD_COORD = 10,	// Invalid world coordinate.
  WCSERR_NO_SOLUTION     = 11,	// No solution found in the specified
				// interval.
  WCSERR_BAD_SUBIMAGE    = 12,	// Invalid subimage specification.
  WCSERR_NON_SEPARABLE   = 13,	// Non-separable subimage coordinate system.
  WCSERR_UNSET           = 14 	// wcsprm struct is unset.
};


// Struct used for storing PVi_ma keywords.
struct pvcard {
  int i;			// Axis number, as in PVi_ma (1-relative).
  int m;			// Parameter number, ditto  (0-relative).
  double value;			// Parameter value.
};

// Size of the pvcard struct in int units, used by the Fortran wrappers.
#define PVLEN (sizeof(struct pvcard)/sizeof(int))

// Struct used for storing PSi_ma keywords.
struct pscard {
  int i;			// Axis number, as in PSi_ma (1-relative).
  int m;			// Parameter number, ditto  (0-relative).
  char value[72];		// Parameter value.
};

// Size of the pscard struct in int units, used by the Fortran wrappers.
#define PSLEN (sizeof(struct pscard)/sizeof(int))

// Struct used to hold additional auxiliary parameters.
struct auxprm {
  double rsun_ref;              // Solar radius.
  double dsun_obs;              // Distance from Sun centre to observer.
  double crln_obs;              // Carrington heliographic lng of observer.
  double hgln_obs;              // Stonyhurst heliographic lng of observer.
  double hglt_obs;              // Heliographic latitude of observer.

  double a_radius;              // Semi-major axis of solar system body.
  double b_radius;              // Semi-intermediate axis of solar system body.
  double c_radius;              // Semi-minor axis of solar system body.
  double blon_obs;              // Bodycentric longitude of observer.
  double blat_obs;              // Bodycentric latitude of observer.
  double bdis_obs;              // Bodycentric distance of observer.
  double dummy[2];              // Reserved for future use.
};

// Size of the auxprm struct in int units, used by the Fortran wrappers.
#define AUXLEN (sizeof(struct auxprm)/sizeof(int))


struct wcsprm {
  // Initialization flag (see the prologue above).
  //--------------------------------------------------------------------------
  int    flag;			// Set to zero to force initialization.

  // FITS header keyvalues to be provided (see the prologue above).
  //--------------------------------------------------------------------------
  int    naxis;			// Number of axes (pixel and coordinate).
  double *crpix;		// CRPIXja keyvalues for each pixel axis.
  double *pc;			// PCi_ja  linear transformation matrix.
  double *cdelt;		// CDELTia keyvalues for each coord axis.
  double *crval;		// CRVALia keyvalues for each coord axis.

  char   (*cunit)[72];		// CUNITia keyvalues for each coord axis.
  char   (*ctype)[72];		// CTYPEia keyvalues for each coord axis.

  double lonpole;		// LONPOLEa keyvalue.
  double latpole;		// LATPOLEa keyvalue.

  double restfrq;		// RESTFRQa keyvalue.
  double restwav;		// RESTWAVa keyvalue.

  int    npv;			// Number of PVi_ma keywords, and the
  int    npvmax;		// number for which space was allocated.
  struct pvcard *pv;		// PVi_ma keywords for each i and m.

  int    nps;			// Number of PSi_ma keywords, and the
  int    npsmax;		// number for which space was allocated.
  struct pscard *ps;		// PSi_ma keywords for each i and m.

  // Alternative header keyvalues (see the prologue above).
  //--------------------------------------------------------------------------
  double *cd;			// CDi_ja linear transformation matrix.
  double *crota;		// CROTAi keyvalues for each coord axis.
  int    altlin;		// Alternative representations
				//   Bit 0: PCi_ja is present,
				//   Bit 1: CDi_ja is present,
				//   Bit 2: CROTAi is present.
  int    velref;		// AIPS velocity code, VELREF.

  // Auxiliary coordinate system information of a general nature.  Not
  // used by WCSLIB.  Refer to the prologue comments above for a brief
  // explanation of these values.
  char   alt[4];
  int    colnum;
  int    *colax;
				// Auxiliary coordinate axis information.
  char   (*cname)[72];
  double *crder;
  double *csyer;
  double *czphs;
  double *cperi;

  char   wcsname[72];
				// Time reference system and measurement.
  char   timesys[72], trefpos[72], trefdir[72], plephem[72];
  char   timeunit[72];
  char   dateref[72];
  double mjdref[2];
  double timeoffs;
				// Data timestamps and durations.
  char   dateobs[72], datebeg[72], dateavg[72], dateend[72];
  double mjdobs, mjdbeg, mjdavg, mjdend;
  double jepoch, bepoch;
  double tstart, tstop;
  double xposure, telapse;
				// Timing accuracy.
  double timsyer, timrder;
  double timedel, timepixr;
				// Spatial & celestial reference frame.
  double obsgeo[6];
  char   obsorbit[72];
  char   radesys[72];
  double equinox;
  char   specsys[72];
  char   ssysobs[72];
  double velosys;
  double zsource;
  char   ssyssrc[72];
  double velangl;

  // Additional auxiliary coordinate system information of a specialist
  // nature.  Not used by WCSLIB.  Refer to the prologue comments above.
  struct auxprm *aux;

  // Coordinate lookup tables (see the prologue above).
  //--------------------------------------------------------------------------
  int    ntab;			// Number of separate tables.
  int    nwtb;			// Number of wtbarr structs.
  struct tabprm *tab;		// Tabular transformation parameters.
  struct wtbarr *wtb;		// Array of wtbarr structs.

  //--------------------------------------------------------------------------
  // Information derived from the FITS header keyvalues by wcsset().
  //--------------------------------------------------------------------------
  char   lngtyp[8], lattyp[8];	// Celestial axis types, e.g. RA, DEC.
  int    lng, lat, spec, time;	// Longitude, latitude, spectral, and time
				// axis indices (0-relative).
  int    cubeface;		// True if there is a CUBEFACE axis.
  int    chksum;		// Checksum of keyvalues provided.
  int    *types;		// Coordinate type codes for each axis.

  struct linprm lin;		//    Linear transformation parameters.
  struct celprm cel;		// Celestial transformation parameters.
  struct spcprm spc;		//  Spectral transformation parameters.

  // Error messaging, if enabled.
  //--------------------------------------------------------------------------
  struct wcserr *err;

  //--------------------------------------------------------------------------
  // Private - the remainder are for internal use.
  //--------------------------------------------------------------------------
				// Memory management.
  int    m_flag, m_naxis;
  double *m_crpix, *m_pc, *m_cdelt, *m_crval;
  char  (*m_cunit)[72], (*m_ctype)[72];
  struct pvcard *m_pv;
  struct pscard *m_ps;
  double *m_cd, *m_crota;
  int    *m_colax;
  char  (*m_cname)[72];
  double *m_crder, *m_csyer, *m_czphs, *m_cperi;
  struct auxprm *m_aux;
  struct tabprm *m_tab;
  struct wtbarr *m_wtb;
};

// Size of the wcsprm struct in int units, used by the Fortran wrappers.
#define WCSLEN (sizeof(struct wcsprm)/sizeof(int))


int wcsnpv(int n);

int wcsnps(int n);

int wcsini(int alloc, int naxis, struct wcsprm *wcs);

int wcsinit(int alloc, int naxis, struct wcsprm *wcs, int npvmax, int npsmax,
            int ndpmax);

int wcsauxi(int alloc, struct wcsprm *wcs);

int wcssub(int alloc, const struct wcsprm *wcssrc, int *nsub, int axes[],
           struct wcsprm *wcsdst);

int wcscompare(int cmp, double tol, const struct wcsprm *wcs1,
               const struct wcsprm *wcs2, int *equal);

int wcsfree(struct wcsprm *wcs);

int wcstrim(struct wcsprm *wcs);

int wcssize(const struct wcsprm *wcs, int sizes[2]);

int auxsize(const struct auxprm *aux, int sizes[2]);

int wcsenq(const struct wcsprm *wcs, int enquiry);

int wcsprt(const struct wcsprm *wcs);

int wcsperr(const struct wcsprm *wcs, const char *prefix);

int wcsbchk(struct wcsprm *wcs, int bounds);

int wcsset(struct wcsprm *wcs);

int wcsp2s(struct wcsprm *wcs, int ncoord, int nelem, const double pixcrd[],
           double imgcrd[], double phi[], double theta[], double world[],
           int stat[]);

int wcss2p(struct wcsprm *wcs, int ncoord, int nelem, const double world[],
           double phi[], double theta[], double imgcrd[], double pixcrd[],
           int stat[]);

int wcsmix(struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[2],
           double vstep, int viter, double world[], double phi[],
           double theta[], double imgcrd[], double pixcrd[]);

int wcsccs(struct wcsprm *wcs, double lng2p1, double lat2p1, double lng1p2,
           const char *clng, const char *clat, const char *radesys,
           double equinox, const char *alt);

int wcssptr(struct wcsprm *wcs, int *i, char ctype[9]);

const char* wcslib_version(int vers[3]);

// Defined mainly for backwards compatibility, use wcssub() instead.
#define wcscopy(alloc, wcssrc, wcsdst) wcssub(alloc, wcssrc, 0x0, 0x0, wcsdst)


// Deprecated.
#define wcsini_errmsg wcs_errmsg
#define wcssub_errmsg wcs_errmsg
#define wcscopy_errmsg wcs_errmsg
#define wcsfree_errmsg wcs_errmsg
#define wcsprt_errmsg wcs_errmsg
#define wcsset_errmsg wcs_errmsg
#define wcsp2s_errmsg wcs_errmsg
#define wcss2p_errmsg wcs_errmsg
#define wcsmix_errmsg wcs_errmsg

#ifdef __cplusplus
#undef wtbarr
}
#endif

#endif // WCSLIB_WCS
@


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: wcs.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: wcs.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: wcs.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
d49 1
a49 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: wcs.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: wcs.h,v 8.5.1.1 2025/12/06 14:05:15 mcalabre Exp mcalabre $
d49 1
a49 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: wcs.h,v 8.3.1.2 2024/07/09 06:25:46 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: wcs.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: wcs.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: wcs.h,v 8.2.1.5 2024/05/13 16:15:46 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.3 - C routines that implement the FITS World Coordinate System
d520 1
a520 1
*                       memory allocation. 
d2240 1
d2242 1
a2242 2
  //             THE REMAINDER OF THE WCSPRM STRUCT IS PRIVATE.
  //--------------------------------------------------------------------------
a2243 1
  // Error handling, if enabled.
d2245 1
a2245 3
  struct wcserr *err;

  // Memory management.
d2247 1
@


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


8.3.1.2
log
@Tweaked some comments in the struct definition.
@
text
@d22 1
a22 1
  $Id: wcs.h,v 8.3.1.1 2024/05/13 16:35:39 mcalabre Exp mcalabre $
d520 1
a520 1
*                       memory allocation.
d2240 5
a2244 1
  // Error messaging, if enabled.
d2248 1
a2249 3
  // Private - the remainder are for internal use.
  //--------------------------------------------------------------------------
				// Memory management.
@


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: wcs.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
d69 4
a72 5
* including allocated memory, and wcsprt() prints its contents.  Refer to the
* description of the wcsprm struct for an explanation of the anticipated usage
* of these routines.  wcscopy(), which does a deep copy of one wcsprm struct
* to another, is defined as a preprocessor macro function that invokes
* wcssub().
d549 29
d658 7
d1173 2
a1174 2
*     (Given and returned) This flag must be set to zero whenever any of the
*     following wcsprm struct members are set or changed:
d1841 6
d2026 1
d2045 7
d2233 1
a2233 1
  int    dummy;			// Dummy for alignment purposes.
d2292 2
@


8.2.1.1
log
@WCSLIB 8.2 development branch.
@
text
@d22 1
a22 1
  $Id: wcs.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: wcs.h,v 8.2.1.1 2023/11/16 10:05:57 mcalabre Exp mcalabre $
@


8.2.1.3
log
@Documented bypass mode in wcsset() and added wcsenq().
@
text
@d22 1
a22 1
  $Id: wcs.h,v 8.2.1.2 2024/04/02 14:01:58 mcalabre Exp mcalabre $
d69 5
a73 4
* including allocated memory, wcsenq() returns information about the state of
* the struct, and wcsprt() prints its contents.  wcscopy(), which does a deep
* copy of one wcsprm struct to another, is defined as a preprocessor macro
* function that invokes wcssub().
a549 26
* wcsenq() - enquire about the state of a wcsprm struct
* -----------------------------------------------------
* wcsenq() may be used to obtain information about the state of a wcsprm
* struct.  The function returns a true/false answer for the enquiry asked.
*
* Given:
*   wcs       const struct wcsprm*
*                       Coordinate transformation parameters.
*
*   enquiry   int       Enquiry according to the following parameters:
*                         WCSENQ_MEM: memory in the struct is being managed by
*                                     WCSLIB (see wcsini()).
*                         WCSENQ_SET: the struct has been set up by wcsset().
*                         WCSENQ_BYP: the struct is in bypass mode, which
*                                     implies that it has been set up (see
*                                     wcsset()).
*                       These may be combined by logical OR, e.g.
*                       WCSENQ_MEM | WCSENQ_SET.  The enquiry result will be
*                       the logical AND of the individual results.
*
* Function return value:
*             int       Enquiry result:
*                         0: No.
*                         1: Yes.
*
*
a629 7
* wcsset() normally operates regardless of the value of wcsprm::flag; i.e.
* even if a struct was previously set up it will be reset unconditionally.
* However, a wcsprm struct may be put into "bypass" mode by invoking wcsset()
* initially with wcsprm::flag == 1 (rather than 0).  wcsset() will return
* immediately if invoked on a struct in that state.  To take a struct out of
* bypass mode, simply reset wcsprm::flag to zero.  See also wcsenq().
*
d1138 2
a1139 2
*     (Given and returned) This flag must be set to zero (or 1, see wcsset())
*     whenever any of the following wcsprm members are set or changed:
a2002 6
enum wcsenq_enum {
  WCSENQ_MEM = 1,		// wcsprm struct memory is managed by WCSLIB.
  WCSENQ_SET = 2,		// wcsprm struct has been set up.
  WCSENQ_BYP = 4,		// wcsprm struct is in bypass mode.
};

a2242 2

int wcsenq(const struct wcsprm *wcs, int enquiry);
@


8.2.1.4
log
@Changed wcsprm::dummy to wcsprm::chksum and documented it.
Added WCSENQ_CHK and amended the prologue comment for wcsenq().
@
text
@d22 1
a22 1
  $Id: wcs.h,v 8.2.1.3 2024/05/08 15:26:39 mcalabre Exp mcalabre $
d562 2
a563 1
*                         WCSENQ_BYP: the struct is in bypass mode (see
a564 4
*                         WCSENQ_CHK: the struct is self-consistent in that
*                                     no changes have been made to any of the
*                                     "parameters to be given" since the last
*                                     call to wcsset().
d571 2
a572 2
*                         0: False.
*                         1: True.
a1837 6
*   int chksum
*     (Returned) Checksum of keyvalues provided (see wcsprm::flag).  Used by
*     wcsenq() to validate the self-consistency of the struct.  Note that
*     the checksum incorporates addresses and is therefore highly specific to
*     the instance of the wcsprm struct.
*
a2038 1
  WCSENQ_CHK = 8,		// wcsprm struct is self-consistent.
d2222 1
a2222 1
  int    chksum;		// Checksum of keyvalues provided.
@


8.2.1.5
log
@Inserted a blank line in the prologue required for document generation.
@
text
@d22 1
a22 1
  $Id: wcs.h,v 8.2.1.4 2024/05/13 14:28:50 mcalabre Exp mcalabre $
a2024 1
*
@


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: wcs.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: wcs.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: wcs.h,v 7.13.1.6 2023/07/01 06:09:15 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: wcs.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: wcs.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
d530 1
a530 1
* auxsize() computes the full size of a auxprm struct, including allocated
d682 3
a684 1
*                       coordinate, in SI units.
d693 4
a696 3
*                       celestial longitude and latitude [deg].  For
*                       spectral axes, imgcrd[][wcs.spec] is the intermediate
*                       spectral coordinate, in SI units.
d744 2
a745 1
*                       SI units.
d760 3
a762 1
*                       spectral coordinate, in SI units.
d1793 3
a1795 1
*     (Returned) ... index for the spectral coordinate in the imgcrd[][] and
d1962 22
d2071 8
d2181 2
a2182 2
  int    lng, lat, spec;	// Longitude, latitude and spectral axis
				// indices (0-relative).
d2184 1
@


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


7.13.1.2
log
@Added wcsprm::time to record the time axis number (along with lng,lat,spec).
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.13.1.1 2022/10/07 03:45:47 mcalabre Exp mcalabre $
d682 1
a682 3
*                       coordinate, in SI units.  For time axes,
*                       imgcrd[][wcs.time] is the intermediate time
*                       coordinate.
d691 3
a693 4
*                       celestial longitude and latitude [deg].  For spectral
*                       axes, world[][wcs.spec] is the spectral coordinate, in
*                       SI units.  For time axes, world[][wcs.time] is the
*                       time coordinate.
d741 1
a741 2
*                       SI units.  For time axes, world[][wcs.time] is the
*                       time coordinate.
d756 1
a756 3
*                       spectral coordinate, in SI units.  For time axes,
*                       imgcrd[][wcs.time] is the intermediate time
*                       coordinate.
d1787 1
a1787 3
*     (Returned) ... index for the spectral coordinate, and ...
*   int time
*     (Returned) ... index for the time coordinate in the imgcrd[][] and
d2143 2
a2144 2
  int    lng, lat, spec, time;	// Longitude, latitude, spectral, and time
				// axis indices (0-relative).
a2145 1
  int    dummy;			// Dummy for alignment purposes.
@


7.13.1.3
log
@Support planetary keywords A_RADIUS, B_RADIUS, C_RADIUS, PLON_OBS, PLAT_OBS,
and PDIS_OBS in auxprm.
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.13.1.2 2023/06/03 05:37:07 mcalabre Exp mcalabre $
d530 1
a530 1
* auxsize() computes the full size of an auxprm struct, including allocated
a1961 22
*   double a_radius
*     Length of the semi-major axis of a triaxial ellipsoid approximating the
*     shape of a body (e.g. planet) in the solar system (m).
*
*   double b_radius
*     Length of the intermediate axis, normal to the semi-major and semi-minor
*     axes, of a triaxial ellipsoid approximating the shape of a body (m).
*
*   double c_radius
*     Length of the semi-minor axis, normal to the semi-major axis, of a
*     triaxial ellipsoid approximating the shape of a body (m).
*
*   double plon_obs
*     Planetocentric longitude of the observer in the coordinate system fixed
*     to the planet or other solar system body (deg, in range 0 to 360).
*
*   double plat_obs
*     Planetocentric latitude of the observer in the coordinate system fixed
*     to the planet or other solar system body (deg).
*
*   double pdis_obs
*     Planetocentric distance of the observer (m).
a2048 7
  double a_radius;              // Semi-major axis of solar system body.
  double b_radius;              // Semi-intermediate axis of solar system body.
  double c_radius;              // Semi-minor axis of solar system body.
  double plon_obs;              // Planetocentric longitude of observer.
  double plat_obs;              // Planetocentric latitude of observer.
  double pdis_obs;              // Planetocentric distance of observer.
  double dummy[2];              // Reserved for future use.
@


7.13.1.4
log
@(PLON_OBS, PLAT_OBS, PDIS_OBS) -> (BLON_OBS, BLAT_OBS, BDIS_OBS).
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.13.1.3 2023/06/03 08:24:14 mcalabre Exp mcalabre $
d1974 7
a1980 7
*   double blon_obs
*     Bodycentric longitude of the observer in the coordinate system fixed to
*     the planet or other solar system body (deg, in range 0 to 360).
*
*   double blat_obs
*     Bodycentric latitude of the observer in the coordinate system fixed to
*     the planet or other solar system body (deg).
d1982 2
a1983 2
*   double bdis_obs
*     Bodycentric distance of the observer (m).
d2074 3
a2076 3
  double blon_obs;              // Bodycentric longitude of observer.
  double blat_obs;              // Bodycentric latitude of observer.
  double bdis_obs;              // Bodycentric distance of observer.
@


7.13.1.5
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2023, Mark Calabretta
d22 1
a22 1
  $Id: wcs.h,v 7.13.1.4 2023/06/15 03:58:10 mcalabre Exp mcalabre $
@


7.13.1.6
log
@Whitespace.
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.13.1.5 2023/06/15 04:17:19 mcalabre Exp mcalabre $
a2070 1

@


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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.h,v 7.9.1.1 2022/03/25 15:16:40 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: wcs.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: wcs.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
@


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


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: wcs.h,v 7.7.1.3 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: wcs.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: wcs.h,v 7.6.1.2 2021/07/01 08:28:44 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.7 - C routines that implement the FITS World Coordinate System
d330 1
d1807 1
d1979 1
@


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


7.7.1.2
log
@In wcssub(), subimage extraction by coordinate type now recognises time
axes via WCSSUB_TIME.  wcsset() now identifies time axes in wcsprm::types.
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.7.1.1 2021/07/12 06:38:27 mcalabre Exp mcalabre $
a329 1
*                         WCSSUB_TIME:      Time axis.
a1805 1
*       - 4: Time coordinate.
a1976 1
#define WCSSUB_TIME      0x1020
@


7.7.1.3
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2022, Mark Calabretta
d22 1
a22 1
  $Id: wcs.h,v 7.7.1.2 2022/03/22 05:13:08 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: wcs.h,v 7.5.1.4 2021/04/13 09:27:51 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.6 - C routines that implement the FITS World Coordinate System
d2218 1
a2218 1
int wcsmix(struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[],
@


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


7.6.1.2
log
@Quelled a warning from gcc 11.1.0 relating to the prototype for wcsmix().
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.6.1.1 2021/04/13 13:00:35 mcalabre Exp mcalabre $
d2218 1
a2218 1
int wcsmix(struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[2],
@


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: wcs.h,v 7.4.1.2 2021/02/22 07:23:26 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.5 - C routines that implement the FITS World Coordinate System
d67 7
a73 6
* wcsnpv(), wcsnps(), wcsini(), wcsinit(), wcssub(), and wcsfree() are
* provided to manage the wcsprm struct and another, wcsprt(), prints its
* contents.  Refer to the description of the wcsprm struct for an explanation
* of the anticipated usage of these routines.  wcscopy(), which does a deep
* copy of one wcsprm struct to another, is defined as a preprocessor macro
* function that invokes wcssub().
d454 34
a487 1
* Returned:
d495 52
d918 1
d1037 5
d1331 8
a1338 8
*       Matrix elements in the IRAF convention are
*       equivalent to the product CDi_ja = CDELTia * PCi_ja, but the
*       defaults differ from that of the PCi_ja matrix.  If one or more
*       CDi_ja keywords are present then all unspecified CDi_ja default to
*       zero.  If no CDi_ja (or CROTAi) keywords are present, then the
*       header is assumed to be in PCi_ja form whether or not any PCi_ja
*       keywords are present since this results in an interpretation of
*       CDELTia consistent with the original FITS specification.
d1345 4
a1348 4
*       In the AIPS convention, CROTAi may only be
*       associated with the latitude axis of a celestial axis pair.  It
*       specifies a rotation in the image plane that is applied AFTER the
*       CDELTia; any other CROTAi keywords are ignored.
d1355 11
a1365 4
*     CDi_ja and CROTAi keywords, if found, are to be stored in the
*     wcsprm::cd and wcsprm::crota arrays which are dimensioned similarly to
*     wcsprm::pc and wcsprm::cdelt.  FITS
*     header parsers should use the following procedure:
d1367 1
a1367 1
*     - Whenever a PCi_ja  keyword is encountered: altlin |= 1;
d1369 1
a1369 1
*     - Whenever a CDi_ja  keyword is encountered: altlin |= 2;
d1378 3
a1380 2
*     lower-level WCSLIB routines.  In particular, wcsset() resets
*     wcsprm::cdelt to unity if CDi_ja is present (and no PCi_ja).
d2006 2
a2007 1
  WCSERR_NON_SEPARABLE   = 13 	// Non-separable subimage coordinate system.
d2079 2
a2080 2
				//   Bit 0: PCi_ja  is present,
				//   Bit 1: CDi_ja  is present,
d2195 6
@


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


7.5.1.2
log
@Augmented the prologue comments for wcsccs() and wcssptr().
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.5.1.1 2021/03/20 05:56:42 mcalabre Exp mcalabre $
a831 1
* The wcsprm struct is reset on return with an explicit call to wcsset().
a949 5
* PLEASE NOTE: Information in the wcsprm struct relating to the original
* coordinate system will be overwritten and therefore lost.  If this is
* undesirable, invoke wcssptr() on a copy of the struct made with wcssub().
* The wcsprm struct is reset on return with an explicit call to wcsset().
*
d1239 8
a1246 8
*       Matrix elements in the IRAF convention are equivalent to the product
*       CDi_ja = CDELTia * PCi_ja, but the defaults differ from that of the
*       PCi_ja matrix.  If one or more CDi_ja keywords are present then all
*       unspecified CDi_ja default to zero.  If no CDi_ja (or CROTAi) keywords
*       are present, then the header is assumed to be in PCi_ja form whether
*       or not any PCi_ja keywords are present since this results in an
*       interpretation of CDELTia consistent with the original FITS
*       specification.
d1253 4
a1256 4
*       In the AIPS convention, CROTAi may only be associated with the
*       latitude axis of a celestial axis pair.  It specifies a rotation in
*       the image plane that is applied AFTER the CDELTia; any other CROTAi
*       keywords are ignored.
@


7.5.1.3
log
@Updated prologue comments relating to wcsprm::altlin.
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.5.1.2 2021/04/09 03:54:49 mcalabre Exp mcalabre $
d1269 4
a1272 1
*     - Bit 3: PCi_ja + CDELTia was derived from CDi_ja by wcspcx().
d1274 1
a1274 4
*       This bit is set by wcspcx() when it derives PCi_ja and CDELTia from
*       CDi_ja via an orthonormal decomposition.  In particular, it signals
*       wcsset() not to replace PCi_ja by a copy of CDi_ja with CDELTia set
*       to unity.
d1276 1
a1276 8
*     CDi_ja and CROTAi keywords, if found, are to be stored in the wcsprm::cd
*     and wcsprm::crota arrays which are dimensioned similarly to wcsprm::pc
*     and wcsprm::cdelt.  FITS header parsers should use the following
*     procedure:
*
*     - Whenever a PCi_ja keyword is encountered: altlin |= 1;
*
*     - Whenever a CDi_ja keyword is encountered: altlin |= 2;
d1285 2
a1286 3
*     lower-level WCSLIB routines.  In particular, unless bit 3 is also set,
*     wcsset() resets wcsprm::cdelt to unity if CDi_ja is present (and no
*     PCi_ja).
d1984 2
a1985 2
				//   Bit 0: PCi_ja is present,
				//   Bit 1: CDi_ja is present,
@


7.5.1.4
log
@Added new functions wcstrim(), wcssize(), and auxsize().  New error code
WCSERR_UNSET for wcstrim().
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.5.1.3 2021/04/10 14:25:00 mcalabre Exp mcalabre $
d67 6
a72 7
* wcsnpv(), wcsnps(), wcsini(), wcsinit(), wcssub(), wcsfree(), and wcstrim(),
* are provided to manage the wcsprm struct, wcssize() computes its total size
* including allocated memory, and wcsprt() prints its contents.  Refer to the
* description of the wcsprm struct for an explanation of the anticipated usage
* of these routines.  wcscopy(), which does a deep copy of one wcsprm struct
* to another, is defined as a preprocessor macro function that invokes
* wcssub().
d453 1
a453 34
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcstrim() - Free unused arrays in the wcsprm struct
* ---------------------------------------------------
* wcstrim() frees memory allocated by wcsinit() for arrays in the wcsprm
* struct that remains unused after it has been set up by wcsset().
*
* The free'd array members are associated with FITS WCS keyrecords that are
* rarely used and usually just bloat the struct: wcsprm::crota, wcsprm::colax,
* wcsprm::cname, wcsprm::crder, wcsprm::csyer, wcsprm::czphs, and
* wcsprm::cperi.  If unused, wcsprm::pv, wcsprm::ps, and wcsprm::cd are also
* freed.
*
* Once these arrays have been freed, a test such as
=
=        if (!undefined(wcs->cname[i])) {...}
=
* must be protected as follows
=
=        if (wcs->cname && !undefined(wcs->cname[i])) {...}
=
* In addition, if wcsprm::npv is non-zero but less than wcsprm::npvmax, then
* the unused space in wcsprm::pv will be recovered (using realloc()).
* Likewise for wcsprm::ps.
*
* Given and returned:
a460 52
*                        14: wcsprm struct is unset.
*
*
* wcssize() - Compute the size of a wcsprm struct
* -----------------------------------------------
* wcssize() computes the full size of a wcsprm struct, including allocated
* memory.
*
* Given:
*   wcs       const struct wcsprm*
*                       Coordinate transformation parameters.
*
*                       If NULL, the base size of the struct and the allocated
*                       size are both set to zero.
*
* Returned:
*   sizes     int[2]    The first element is the base size of the struct as
*                       returned by sizeof(struct wcsprm).  The second element
*                       is the total allocated size, in bytes, assuming that
*                       the allocation was done by wcsini().  This figure
*                       includes memory allocated for members of constituent
*                       structs, such as wcsprm::lin.
*
*                       It is not an error for the struct not to have been set
*                       up via wcsset(), which normally results in additional
*                       memory allocation. 
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*
*
* auxsize() - Compute the size of a auxprm struct
* -----------------------------------------------
* auxsize() computes the full size of a auxprm struct, including allocated
* memory.
*
* Given:
*   aux       const struct auxprm*
*                       Auxiliary coordinate information.
*
*                       If NULL, the base size of the struct and the allocated
*                       size are both set to zero.
*
* Returned:
*   sizes     int[2]    The first element is the base size of the struct as
*                       returned by sizeof(struct auxprm).  The second element
*                       is the total allocated size, in bytes, currently zero.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
d1920 1
a1920 2
  WCSERR_NON_SEPARABLE   = 13,	// Non-separable subimage coordinate system.
  WCSERR_UNSET           = 14 	// wcsprm struct is unset.
a2107 6

int wcstrim(struct wcsprm *wcs);

int wcssize(const struct wcsprm *wcs, int sizes[2]);

int auxsize(const struct auxprm *aux, int sizes[2]);
@


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: wcs.h,v 7.3.1.6 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
d91 4
a94 2
* wcssptr() translates the spectral axis in a wcsprm struct.  For example, a
* 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
d810 135
d2114 4
@


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


7.4.1.2
log
@Added new function wcsccs().
@
text
@d22 1
a22 1
  $Id: wcs.h,v 7.4.1.1 2021/01/31 02:26:24 mcalabre Exp mcalabre $
d91 2
a92 4
* wcsccs() changes the celestial coordinate system of a wcsprm struct, for
* example, from equatorial to galactic, and wcssptr() translates the spectral
* axis.  For example, a 'FREQ' axis may be translated into 'ZOPT-F2W' and vice
* versa.
a807 135
* wcsccs() - Change celestial coordinate system
* ---------------------------------------------
* wcsccs() changes the celestial coordinate system of a wcsprm struct.  For
* example, from equatorial to galactic coordinates.
*
* Parameters that define the spherical coordinate transformation, essentially
* being three Euler angles, must be provided.  Thereby wcsccs() does not need
* prior knowledge of specific celestial coordinate systems.  It also has the
* advantage of making it completely general.
*
* Auxiliary members of the wcsprm struct relating to equatorial celestial
* coordinate systems may also be changed.
*
* Only orthodox spherical coordinate systems are supported.  That is, they
* must be right-handed, with latitude increasing from zero at the equator to
* +90 degrees at the pole.  This precludes systems such as aziumuth and zenith
* distance, which, however, could be handled as negative azimuth and
* elevation.
*
* PLEASE NOTE: Information in the wcsprm struct relating to the original
* coordinate system will be overwritten and therefore lost.  If this is
* undesirable, invoke wcsccs() on a copy of the struct made with wcssub().
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.  Particular
*                       "values to be given" elements of the wcsprm struct
*                       are modified.
*
* Given:
*   lng2p1,
*   lat2p1    double    Longitude and latitude in the new celestial coordinate
*                       system of the pole (i.e. latitude +90) of the original
*                       system [deg].  See notes 1 and 2 below.
*
*   lng1p2    double    Longitude in the original celestial coordinate system
*                       of the pole (i.e. latitude +90) of the new system
*                       [deg].  See note 1 below.
*
*   clng,clat const char*
*                       Longitude and latitude identifiers of the new CTYPEia
*                       celestial axis codes, without trailing dashes.  For
*                       example, "RA" and "DEC" or "GLON" and "GLAT".  Up to
*                       four characters are used, longer strings need not be
*                       null-terminated.
*
*   radesys   const char*
*                       Used when transforming to equatorial coordinates,
*                       identified by clng == "RA" and clat = "DEC".  May be
*                       set to the null pointer to preserve the current value.
*                       Up to 71 characters are used, longer strings need not
*                       be null-terminated.
*
*                       If the new coordinate system is anything other than
*                       equatorial, then wcsprm::radesys will be cleared.
*
*   equinox   double    Used when transforming to equatorial coordinates.  May
*                       be set to zero to preserve the current value.
*
*                       If the new coordinate system is not equatorial, then
*                       wcsprm::equinox will be marked as undefined.
*
*   alt       const char*
*                       Character code for alternate coordinate descriptions
*                       (i.e. the 'a' in keyword names such as CTYPEia).  This
*                       is blank for the primary coordinate description, or
*                       one of the 26 upper-case letters, A-Z.  May be set to
*                       the null pointer, or null string if no change is
*                       required.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                        12: Invalid subimage specification (no celestial
*                            axes).
*
* Notes:
*   1: Follows the prescription given in WCS Paper II, Sect. 2.7 for changing
*      celestial coordinates.
*
*      The implementation takes account of indeterminacies that arise in that
*      prescription in the particular cases where one of the poles of the new
*      system is at the fiducial point, or one of them is at the native pole.
*
*   2: If lat2p1 == +90, i.e. where the poles of the two coordinate systems
*      coincide, then the spherical coordinate transformation becomes a simple
*      change in origin of longitude given by
*      lng2 = lng1 + (lng2p1 - lng1p2 - 180), and lat2 = lat1, where
*      (lng2,lat2) are coordinates in the new system, and (lng1,lat1) are
*      coordinates in the original system.
*
*      Likewise, if lat2p1 == -90, then lng2 = -lng1 + (lng2p1 + lng1p2), and
*      lat2 = -lat1.
*
*   3: For example, if the original coordinate system is B1950 equatorial and
*      the desired new coordinate system is galactic, then
*
*      - (lng2p1,lat2p1) are the galactic coordinates of the B1950 celestial
*        pole, defined by the IAU to be (123.0,+27.4), and lng1p2 is the B1950
*        right ascension of the galactic pole, defined as 192.25.  Clearly
*        these coordinates are fixed for a particular coordinate
*        transformation.
*
*      - (clng,clat) would be 'GLON' and 'GLAT', these being the FITS standard
*        identifiers for galactic coordinates.
*
*      - Since the new coordinate system is not equatorial, wcsprm::radesys
*        and wcsprm::equinox will be cleared.
*
*   4. The coordinates required for some common transformations (obtained from
*      https://ned.ipac.caltech.edu/coordinate_calculator) are as follows:
*
=      (123.0000,+27.4000) galactic coordinates of B1950 celestial pole,
=      (192.2500,+27.4000) B1950 equatorial coordinates of galactic pole.
*
=      (122.9319,+27.1283) galactic coordinates of J2000 celestial pole,
=      (192.8595,+27.1283) J2000 equatorial coordinates of galactic pole.
*
=      (359.6774,+89.7217) B1950 equatorial coordinates of J2000 pole,
=      (180.3162,+89.7217) J2000 equatorial coordinates of B1950 pole.
*
=      (270.0000,+66.5542) B1950 equatorial coordinates of B1950 ecliptic pole,
=      ( 90.0000,+66.5542) B1950 ecliptic coordinates of B1950 celestial pole.
*
=      (270.0000,+66.5607) J2000 equatorial coordinates of J2000 ecliptic pole,
=      ( 90.0000,+66.5607) J2000 ecliptic coordinates of J2000 celestial pole.
*
=      ( 26.7315,+15.6441) supergalactic coordinates of B1950 celestial pole,
=      (283.1894,+15.6441) B1950 equatorial coordinates of supergalactic pole.
*
=      ( 26.4505,+15.7089) supergalactic coordinates of J2000 celestial pole,
=      (283.7542,+15.7089) J2000 equatorial coordinates of supergalactic pole.
*
*
a1976 4

int wcsccs(struct wcsprm *wcs, double lng2p1, double lat2p1, double lng1p2,
           const char *clng, const char *clat, const char *radesys,
           double equinox, const char *alt);
@


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: wcs.h,v 7.2.1.1 2020/03/09 07:34:50 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.3 - C routines that implement the FITS World Coordinate System
d358 33
a390 32
*   Combinations of subimage axes of particular types may be extracted in the
*   same order as they occur in the input image by combining preprocessor
*   codes, for example
*
=     *nsub = 1;
=     axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
*
*   would extract the longitude, latitude, and spectral axes in the same order
*   as the input image.  If one of each were present, *nsub = 3 would be
*   returned.
*
*   For convenience, WCSSUB_CELESTIAL is defined as the combination
*   WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
*
*   The codes may also be negated to extract all but the types specified, for
*   example
*
=     *nsub = 4;
=     axes[0] = WCSSUB_LONGITUDE;
=     axes[1] = WCSSUB_LATITUDE;
=     axes[2] = WCSSUB_CUBEFACE;
=     axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
*
*   The last of these specifies all axis types other than spectral or Stokes.
*   Extraction is done in the order specified by axes[] a longitude axis (if
*   present) would be extracted first (via axes[0]) and not subsequently (via
*   axes[3]).  Likewise for the latitude and cubeface axes in this example.
*
*   From the foregoing, it is apparent that the value of *nsub returned may be
*   less than or greater than that given.  However, it will never exceed the
*   number of axes in the input image (plus the number of newly-created axes
*   if any were specified on input).
d562 3
a564 3
*   wcsset() always enables strict bounds checking in the projection routines
*   (via a call to prjini()).  Use wcsbchk() to modify bounds-checking after
*   wcsset() is invoked.
d781 25
a805 25
*   Initially the specified solution interval is checked to see if it's a
*   "crossing" interval.  If it isn't, a search is made for a crossing
*   solution by iterating on the unknown celestial coordinate starting at the
*   upper limit of the solution interval and decrementing by the specified
*   step size.  A crossing is indicated if the trial value of the pixel
*   coordinate steps through the value specified.  If a crossing interval is
*   found then the solution is determined by a modified form of "regula falsi"
*   division of the crossing interval.  If no crossing interval was found
*   within the specified solution interval then a search is made for a
*   "non-crossing" solution as may arise from a point of tangency.  The
*   process is complicated by having to make allowance for the discontinuities
*   that occur in all map projections.
*
*   Once one solution has been determined others may be found by subsequent
*   invokations of wcsmix() with suitably restricted solution intervals.
*
*   Note the circumstance that arises when the solution point lies at a native
*   pole of a projection in which the pole is represented as a finite curve,
*   for example the zenithals and conics.  In such cases two or more valid
*   solutions may exist but wcsmix() only ever returns one.
*
*   Because of its generality wcsmix() is very compute-intensive.  For
*   compute-limited applications more efficient special-case solvers could be
*   written for simple projections, for example non-oblique cylindrical
*   projections.
d929 2
a930 2
*     returned members of the celprm struct.  celset() will reset flag to
*     indicate that this has been done.
d1731 1
a1731 1
#define wtbarr wtbarr_s		/* See prologue of wtbarr.h.                */
d1750 20
a1769 22
  WCSERR_SUCCESS         =  0,	/* Success. */
  WCSERR_NULL_POINTER    =  1,	/* Null wcsprm pointer passed. */
  WCSERR_MEMORY          =  2,	/* Memory allocation failed. */
  WCSERR_SINGULAR_MTX    =  3,	/* Linear transformation matrix is
				   singular. */
  WCSERR_BAD_CTYPE       =  4,	/* Inconsistent or unrecognized coordinate
				   axis type. */
  WCSERR_BAD_PARAM       =  5,	/* Invalid parameter value. */
  WCSERR_BAD_COORD_TRANS =  6,	/* Unrecognized coordinate transformation
				   parameter. */
  WCSERR_ILL_COORD_TRANS =  7,	/* Ill-conditioned coordinate transformation
				   parameter. */
  WCSERR_BAD_PIX         =  8,	/* One or more of the pixel coordinates were
				   invalid. */
  WCSERR_BAD_WORLD       =  9,	/* One or more of the world coordinates were
				   invalid. */
  WCSERR_BAD_WORLD_COORD = 10,	/* Invalid world coordinate. */
  WCSERR_NO_SOLUTION     = 11,	/* No solution found in the specified
				   interval. */
  WCSERR_BAD_SUBIMAGE    = 12,	/* Invalid subimage specification. */
  WCSERR_NON_SEPARABLE   = 13 	/* Non-separable subimage coordinate
				   system. */
d1773 1
a1773 1
/* Struct used for storing PVi_ma keywords. */
d1775 3
a1777 3
  int i;			/* Axis number, as in PVi_ma (1-relative).  */
  int m;			/* Parameter number, ditto  (0-relative).   */
  double value;			/* Parameter value.                         */
d1780 1
a1780 1
/* Size of the pvcard struct in int units, used by the Fortran wrappers. */
d1783 1
a1783 1
/* Struct used for storing PSi_ma keywords. */
d1785 3
a1787 3
  int i;			/* Axis number, as in PSi_ma (1-relative).  */
  int m;			/* Parameter number, ditto  (0-relative).   */
  char value[72];		/* Parameter value.                         */
d1790 1
a1790 1
/* Size of the pscard struct in int units, used by the Fortran wrappers. */
d1793 1
a1793 1
/* Struct used to hold additional auxiliary parameters.                     */
d1795 5
a1799 5
  double rsun_ref;              /* Solar radius.                            */
  double dsun_obs;              /* Distance from Sun centre to observer.    */
  double crln_obs;              /* Carrington heliographic lng of observer. */
  double hgln_obs;              /* Stonyhurst heliographic lng of observer. */
  double hglt_obs;              /* Heliographic latitude of observer.       */
d1802 1
a1802 1
/* Size of the auxprm struct in int units, used by the Fortran wrappers. */
d1807 42
a1848 42
  /* Initialization flag (see the prologue above).                          */
  /*------------------------------------------------------------------------*/
  int    flag;			/* Set to zero to force initialization.     */

  /* FITS header keyvalues to be provided (see the prologue above).         */
  /*------------------------------------------------------------------------*/
  int    naxis;			/* Number of axes (pixel and coordinate).   */
  double *crpix;		/* CRPIXja keyvalues for each pixel axis.   */
  double *pc;			/* PCi_ja  linear transformation matrix.    */
  double *cdelt;		/* CDELTia keyvalues for each coord axis.   */
  double *crval;		/* CRVALia keyvalues for each coord axis.   */

  char   (*cunit)[72];		/* CUNITia keyvalues for each coord axis.   */
  char   (*ctype)[72];		/* CTYPEia keyvalues for each coord axis.   */

  double lonpole;		/* LONPOLEa keyvalue.                       */
  double latpole;		/* LATPOLEa keyvalue.                       */

  double restfrq;		/* RESTFRQa keyvalue.                       */
  double restwav;		/* RESTWAVa keyvalue.                       */

  int    npv;			/* Number of PVi_ma keywords, and the       */
  int    npvmax;		/* number for which space was allocated.    */
  struct pvcard *pv;		/* PVi_ma keywords for each i and m.        */

  int    nps;			/* Number of PSi_ma keywords, and the       */
  int    npsmax;		/* number for which space was allocated.    */
  struct pscard *ps;		/* PSi_ma keywords for each i and m.        */

  /* Alternative header keyvalues (see the prologue above).                 */
  /*------------------------------------------------------------------------*/
  double *cd;			/* CDi_ja linear transformation matrix.     */
  double *crota;		/* CROTAi keyvalues for each coord axis.    */
  int    altlin;		/* Alternative representations              */
				/*   Bit 0: PCi_ja  is present,             */
				/*   Bit 1: CDi_ja  is present,             */
				/*   Bit 2: CROTAi is present.              */
  int    velref;		/* AIPS velocity code, VELREF.              */

  /* Auxiliary coordinate system information of a general nature.  Not      */
  /* used by WCSLIB.  Refer to the prologue comments above for a brief      */
  /* explanation of these values.                                           */
d1852 1
a1852 1
				/* Auxiliary coordinate axis information.   */
d1860 1
a1860 1
				/* Time reference system and measurement.   */
d1866 1
a1866 1
				/* Data timestamps and durations.           */
d1872 1
a1872 1
				/* Timing accuracy.                         */
d1875 1
a1875 1
				/* Spatial & celestial reference frame.     */
d1887 2
a1888 2
  /* Additional auxiliary coordinate system information of a specialist     */
  /* nature.  Not used by WCSLIB.  Refer to the prologue comments above.    */
d1891 23
a1913 23
  /* Coordinate lookup tables (see the prologue above).                     */
  /*------------------------------------------------------------------------*/
  int    ntab;			/* Number of separate tables.               */
  int    nwtb;			/* Number of wtbarr structs.                */
  struct tabprm *tab;		/* Tabular transformation parameters.       */
  struct wtbarr *wtb;		/* Array of wtbarr structs.                 */

  /*------------------------------------------------------------------------*/
  /* Information derived from the FITS header keyvalues by wcsset().        */
  /*------------------------------------------------------------------------*/
  char   lngtyp[8], lattyp[8];	/* Celestial axis types, e.g. RA, DEC.      */
  int    lng, lat, spec;	/* Longitude, latitude and spectral axis    */
				/* indices (0-relative).                    */
  int    cubeface;		/* True if there is a CUBEFACE axis.        */
  int    *types;		/* Coordinate type codes for each axis.     */

  struct linprm lin;		/*    Linear transformation parameters.     */
  struct celprm cel;		/* Celestial transformation parameters.     */
  struct spcprm spc;		/*  Spectral transformation parameters.     */

  /*------------------------------------------------------------------------*/
  /*             THE REMAINDER OF THE WCSPRM STRUCT IS PRIVATE.             */
  /*------------------------------------------------------------------------*/
d1915 2
a1916 2
  /* Error handling, if enabled.                                            */
  /*------------------------------------------------------------------------*/
d1919 2
a1920 2
  /* Memory management.                                                     */
  /*------------------------------------------------------------------------*/
d1935 1
a1935 1
/* Size of the wcsprm struct in int units, used by the Fortran wrappers. */
d1982 1
a1982 1
/* Defined mainly for backwards compatibility, use wcssub() instead. */
d1986 1
a1986 1
/* Deprecated. */
d2002 1
a2002 1
#endif /* WCSLIB_WCS */
@


7.3.1.1
log
@WCSLIB 7.3 development branch.
@
text
@d25 1
a25 1
  $Id: wcs.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: wcs.h,v 7.3.1.1 2020/06/03 03:38:10 mcalabre Exp mcalabre $
d1733 1
a1733 1
#define wtbarr wtbarr_s		// See prologue of wtbarr.h.
d1752 22
a1773 20
  WCSERR_SUCCESS         =  0,	// Success.
  WCSERR_NULL_POINTER    =  1,	// Null wcsprm pointer passed.
  WCSERR_MEMORY          =  2,	// Memory allocation failed.
  WCSERR_SINGULAR_MTX    =  3,	// Linear transformation matrix is singular.
  WCSERR_BAD_CTYPE       =  4,	// Inconsistent or unrecognized coordinate
				// axis type.
  WCSERR_BAD_PARAM       =  5,	// Invalid parameter value.
  WCSERR_BAD_COORD_TRANS =  6,	// Unrecognized coordinate transformation
				// parameter.
  WCSERR_ILL_COORD_TRANS =  7,	// Ill-conditioned coordinate transformation
				// parameter.
  WCSERR_BAD_PIX         =  8,	// One or more of the pixel coordinates were
				// invalid.
  WCSERR_BAD_WORLD       =  9,	// One or more of the world coordinates were
				// invalid.
  WCSERR_BAD_WORLD_COORD = 10,	// Invalid world coordinate.
  WCSERR_NO_SOLUTION     = 11,	// No solution found in the specified
				// interval.
  WCSERR_BAD_SUBIMAGE    = 12,	// Invalid subimage specification.
  WCSERR_NON_SEPARABLE   = 13 	// Non-separable subimage coordinate system.
d1777 1
a1777 1
// Struct used for storing PVi_ma keywords.
d1779 3
a1781 3
  int i;			// Axis number, as in PVi_ma (1-relative).
  int m;			// Parameter number, ditto  (0-relative).
  double value;			// Parameter value.
d1784 1
a1784 1
// Size of the pvcard struct in int units, used by the Fortran wrappers.
d1787 1
a1787 1
// Struct used for storing PSi_ma keywords.
d1789 3
a1791 3
  int i;			// Axis number, as in PSi_ma (1-relative).
  int m;			// Parameter number, ditto  (0-relative).
  char value[72];		// Parameter value.
d1794 1
a1794 1
// Size of the pscard struct in int units, used by the Fortran wrappers.
d1797 1
a1797 1
// Struct used to hold additional auxiliary parameters.
d1799 5
a1803 5
  double rsun_ref;              // Solar radius.
  double dsun_obs;              // Distance from Sun centre to observer.
  double crln_obs;              // Carrington heliographic lng of observer.
  double hgln_obs;              // Stonyhurst heliographic lng of observer.
  double hglt_obs;              // Heliographic latitude of observer.
d1806 1
a1806 1
// Size of the auxprm struct in int units, used by the Fortran wrappers.
d1811 42
a1852 42
  // Initialization flag (see the prologue above).
  //--------------------------------------------------------------------------
  int    flag;			// Set to zero to force initialization.

  // FITS header keyvalues to be provided (see the prologue above).
  //--------------------------------------------------------------------------
  int    naxis;			// Number of axes (pixel and coordinate).
  double *crpix;		// CRPIXja keyvalues for each pixel axis.
  double *pc;			// PCi_ja  linear transformation matrix.
  double *cdelt;		// CDELTia keyvalues for each coord axis.
  double *crval;		// CRVALia keyvalues for each coord axis.

  char   (*cunit)[72];		// CUNITia keyvalues for each coord axis.
  char   (*ctype)[72];		// CTYPEia keyvalues for each coord axis.

  double lonpole;		// LONPOLEa keyvalue.
  double latpole;		// LATPOLEa keyvalue.

  double restfrq;		// RESTFRQa keyvalue.
  double restwav;		// RESTWAVa keyvalue.

  int    npv;			// Number of PVi_ma keywords, and the
  int    npvmax;		// number for which space was allocated.
  struct pvcard *pv;		// PVi_ma keywords for each i and m.

  int    nps;			// Number of PSi_ma keywords, and the
  int    npsmax;		// number for which space was allocated.
  struct pscard *ps;		// PSi_ma keywords for each i and m.

  // Alternative header keyvalues (see the prologue above).
  //--------------------------------------------------------------------------
  double *cd;			// CDi_ja linear transformation matrix.
  double *crota;		// CROTAi keyvalues for each coord axis.
  int    altlin;		// Alternative representations
				//   Bit 0: PCi_ja  is present,
				//   Bit 1: CDi_ja  is present,
				//   Bit 2: CROTAi is present.
  int    velref;		// AIPS velocity code, VELREF.

  // Auxiliary coordinate system information of a general nature.  Not
  // used by WCSLIB.  Refer to the prologue comments above for a brief
  // explanation of these values.
d1856 1
a1856 1
				// Auxiliary coordinate axis information.
d1864 1
a1864 1
				// Time reference system and measurement.
d1870 1
a1870 1
				// Data timestamps and durations.
d1876 1
a1876 1
				// Timing accuracy.
d1879 1
a1879 1
				// Spatial & celestial reference frame.
d1891 2
a1892 2
  // Additional auxiliary coordinate system information of a specialist
  // nature.  Not used by WCSLIB.  Refer to the prologue comments above.
d1895 23
a1917 23
  // Coordinate lookup tables (see the prologue above).
  //--------------------------------------------------------------------------
  int    ntab;			// Number of separate tables.
  int    nwtb;			// Number of wtbarr structs.
  struct tabprm *tab;		// Tabular transformation parameters.
  struct wtbarr *wtb;		// Array of wtbarr structs.

  //--------------------------------------------------------------------------
  // Information derived from the FITS header keyvalues by wcsset().
  //--------------------------------------------------------------------------
  char   lngtyp[8], lattyp[8];	// Celestial axis types, e.g. RA, DEC.
  int    lng, lat, spec;	// Longitude, latitude and spectral axis
				// indices (0-relative).
  int    cubeface;		// True if there is a CUBEFACE axis.
  int    *types;		// Coordinate type codes for each axis.

  struct linprm lin;		//    Linear transformation parameters.
  struct celprm cel;		// Celestial transformation parameters.
  struct spcprm spc;		//  Spectral transformation parameters.

  //--------------------------------------------------------------------------
  //             THE REMAINDER OF THE WCSPRM STRUCT IS PRIVATE.
  //--------------------------------------------------------------------------
d1919 2
a1920 2
  // Error handling, if enabled.
  //--------------------------------------------------------------------------
d1923 2
a1924 2
  // Memory management.
  //--------------------------------------------------------------------------
d1939 1
a1939 1
// Size of the wcsprm struct in int units, used by the Fortran wrappers.
d1986 1
a1986 1
// Defined mainly for backwards compatibility, use wcssub() instead.
d1990 1
a1990 1
// Deprecated.
d2006 1
a2006 1
#endif // WCSLIB_WCS
@


7.3.1.3
log
@Amended the prologue comment relating to wcsprm::flag.
@
text
@d24 1
a24 1
  $Id: wcs.h,v 7.3.1.2 2020/08/17 12:10:44 mcalabre Exp mcalabre $
d930 2
a931 2
*     returned members of the linprm, celprm, spcprm, and tabprm structs.
*     wcsset() will reset flag to indicate that this has been done.
@


7.3.1.4
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2021, Mark Calabretta
d24 1
a24 1
  $Id: wcs.h,v 7.3.1.3 2020/08/17 12:44:51 mcalabre Exp mcalabre $
@


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


7.3.1.6
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: wcs.h,v 7.3.1.5 2021/01/28 12:29:30 mcalabre Exp mcalabre $
d358 32
a389 33
*   1: Combinations of subimage axes of particular types may be extracted in
*      the same order as they occur in the input image by combining
*      preprocessor codes, for example
*
=        *nsub = 1;
=        axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
*
*      would extract the longitude, latitude, and spectral axes in the same
*      order as the input image.  If one of each were present, *nsub = 3 would
*      be returned.
*
*      For convenience, WCSSUB_CELESTIAL is defined as the combination
*      WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
*
*      The codes may also be negated to extract all but the types specified,
*      for example
*
=        *nsub = 4;
=        axes[0] = WCSSUB_LONGITUDE;
=        axes[1] = WCSSUB_LATITUDE;
=        axes[2] = WCSSUB_CUBEFACE;
=        axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
*
*      The last of these specifies all axis types other than spectral or
*      Stokes.  Extraction is done in the order specified by axes[] a
*      longitude axis (if present) would be extracted first (via axes[0]) and
*      not subsequently (via axes[3]).  Likewise for the latitude and cubeface
*      axes in this example.
*
*      From the foregoing, it is apparent that the value of *nsub returned may
*      be less than or greater than that given.  However, it will never exceed
*      the number of axes in the input image (plus the number of newly-created
*      axes if any were specified on input).
d561 3
a563 3
*   1: wcsset() always enables strict bounds checking in the projection
*      routines (via a call to prjini()).  Use wcsbchk() to modify
*      bounds-checking after wcsset() is invoked.
d780 25
a804 25
*   1: Initially the specified solution interval is checked to see if it's a
*      "crossing" interval.  If it isn't, a search is made for a crossing
*      solution by iterating on the unknown celestial coordinate starting at
*      the upper limit of the solution interval and decrementing by the
*      specified step size.  A crossing is indicated if the trial value of the
*      pixel coordinate steps through the value specified.  If a crossing
*      interval is found then the solution is determined by a modified form of
*      "regula falsi" division of the crossing interval.  If no crossing
*      interval was found within the specified solution interval then a search
*      is made for a "non-crossing" solution as may arise from a point of
*      tangency.  The process is complicated by having to make allowance for
*      the discontinuities that occur in all map projections.
*
*      Once one solution has been determined others may be found by subsequent
*      invokations of wcsmix() with suitably restricted solution intervals.
*
*      Note the circumstance that arises when the solution point lies at a
*      native pole of a projection in which the pole is represented as a
*      finite curve, for example the zenithals and conics.  In such cases two
*      or more valid solutions may exist but wcsmix() only ever returns one.
*
*      Because of its generality wcsmix() is very compute-intensive.  For
*      compute-limited applications more efficient special-case solvers could
*      be written for simple projections, for example non-oblique cylindrical
*      projections.
@


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: wcs.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
@


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


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: wcs.h,v 6.4.1.3 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: wcs.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: wcs.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
d183 3
a185 1
*                       crpix, etc. arrays.
d234 28
d415 1
a415 1
*                           the same grid map.  Overrides WCSCOMPARE_TILING.
d1501 9
d1689 29
d1797 12
d1850 3
a1852 2
  /* Auxiliary coordinate system information, not used by WCSLIB.  Refer to */
  /* the prologue comments above for a brief explanation of these values.   */
d1891 4
d1934 1
d1951 2
@


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


6.4.1.2
log
@Added the auxprm struct to hold additional auxiliary coordinate system
information, initially containing five Solar-related keyvalues.  New
function wcsauxi() initialises an auxprm struct.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 6.4.1.1 2019/08/15 09:31:29 mcalabre Exp mcalabre $
d183 1
a183 3
*                       crpix, etc. arrays.  Please note that memory is never
*                       allocated by wcsinit() for the auxprm, tabprm, nor
*                       wtbarr structs.
a231 28
* wcsauxi() - Default constructor for the auxprm struct
* -----------------------------------------------------
* wcsauxi() optionally allocates memory for an auxprm struct, attaches it to
* wcsprm, and sets all members of the struct to default values.
*
* Given:
*   alloc     int       If true, allocate memory unconditionally for the
*                       auxprm struct.
*
*                       If false, it is assumed that wcsprm::aux has already
*                       been set to point to an auxprm struct, in which case
*                       the user is responsible for managing that memory.
*                       However, if wcsprm::aux is a null pointer, memory will
*                       be allocated regardless.  (In other words, setting
*                       alloc true saves having to initalize the pointer to
*                       zero.)
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*
*
d385 1
a385 1
*                           the same map grid.  Overrides WCSCOMPARE_TILING.
a1470 9
*   struct auxprm *aux
*     (Given, auxiliary) This struct holds auxiliary coordinate system
*     information of a specialist nature.  While these parameters may be
*     widely recognized within particular fields of astronomy, they differ
*     from the above auxiliary parameters in not being defined by any of the
*     FITS WCS standards.  Collecting them together in a separate struct that
*     is allocated only when required helps to control bloat in the size of
*     the wcsprm struct.
*
a1649 29
* auxprm struct - Additional auxiliary parameters
* -----------------------------------------------
* The auxprm struct holds auxiliary coordinate system information of a
* specialist nature.  It is anticipated that this struct will expand in future
* to accomodate additional parameters.
*
* All members of this struct are to be set by the user.
*
*   double rsun_ref
*     (Given, auxiliary) Reference radius of the Sun used in coordinate
*     calculations (m).
*
*   double dsun_obs
*     (Given, auxiliary) Distance between the centre of the Sun and the
*     observer (m).
*
*   double crln_obs
*     (Given, auxiliary) Carrington heliographic longitude of the observer
*     (deg).
*
*   double hgln_obs
*     (Given, auxiliary) Stonyhurst heliographic longitude of the observer
*     (deg).
*
*   double hglt_obs
*     (Given, auxiliary) Heliographic latitude (Carrington or Stonyhurst) of
*     the observer (deg).
*
*
a1728 12
/* Struct used to hold additional auxiliary parameters.                     */
struct auxprm {
  double rsun_ref;              /* Solar radius.                            */
  double dsun_obs;              /* Distance from Sun centre to observer.    */
  double crln_obs;              /* Carrington heliographic lng of observer. */
  double hgln_obs;              /* Stonyhurst heliographic lng of observer. */
  double hglt_obs;              /* Heliographic latitude of observer.       */
};

/* Size of the auxprm struct in int units, used by the Fortran wrappers. */
#define AUXLEN (sizeof(struct auxprm)/sizeof(int))

d1770 2
a1771 3
  /* Auxiliary coordinate system information of a general nature.  Not      */
  /* used by WCSLIB.  Refer to the prologue comments above for a brief      */
  /* explanation of these values.                                           */
a1809 4
  /* Additional auxiliary coordinate system information of a specialist     */
  /* nature.  Not used by WCSLIB.  Refer to the prologue comments above.    */
  struct auxprm *aux;

a1848 1
  struct auxprm *m_aux;
a1864 2

int wcsauxi(int alloc, struct wcsprm *wcs);
@


6.4.1.3
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2020, Mark Calabretta
d25 1
a25 1
  $Id: wcs.h,v 6.4.1.2 2019/12/31 02:21:58 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: wcs.h,v 6.2.1.2 2019/05/10 01:56:50 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: wcs.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: wcs.h,v 6.1.1.2 2018/10/20 09:34:53 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.2 - C routines that implement the FITS World Coordinate System
@


6.2.1.1
log
@WCSLIB 6.2 development branch.
@
text
@d25 1
a25 1
  $Id: wcs.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: wcs.h,v 6.2.1.1 2018/10/20 10:04:15 mcalabre Exp mcalabre $
@


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: wcs.h,v 5.20.1.2 2018/10/19 06:22:54 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.1 - C routines that implement the FITS World Coordinate System
d1062 1
a1062 1
*     (Given) ... those associated with the CROTAia keywords.  Although these
d1068 1
a1068 1
*     and CROTAia keywords are present in the header:
d1078 1
a1078 1
*       zero.  If no CDi_ja (or CROTAia) keywords are present, then the
d1084 1
a1084 1
*       with CDELTia and CROTAia which are to be ignored.
d1086 1
a1086 1
*     - Bit 2: CROTAia is present.
d1088 1
a1088 1
*       In the AIPS convention, CROTAia may only be
d1091 1
a1091 1
*       CDELTia; any other CROTAia keywords are ignored.
d1093 1
a1093 1
*       CROTAia may not formally co-exist with PCi_ja.
d1095 1
a1095 1
*       CROTAia and CDELTia may formally co-exist with CDi_ja but if so are to
d1098 1
a1098 1
*     CDi_ja and CROTAia keywords, if found, are to be stored in the
d1107 1
a1107 1
*     - Whenever a CROTAia keyword is encountered: altlin |= 4;
d1117 1
a1117 1
*     If CROTAia are present but none is associated with the latitude axis
d1363 1
a1363 1
*     between DATE-BEG and DATE-END, in units of TIMEUNIT, 
a1556 3
*   void *padding
*     (An unused variable inserted for alignment purposes only.)
*
a1572 2
*   void *m_padding
*     (For internal use only.)
d1665 1
d1763 1
a1763 1
  double *crota;		/* CROTAia keyvalues for each coord axis.   */
d1767 1
a1767 1
				/*   Bit 2: CROTAia is present.             */
d1914 1
@


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


6.1.1.2
log
@Replaced the #define of wtbarr, which is required for C++ compilation.
CROTAia (non-standard) -> CROTAi.  Removed the padding variables from the
documentation for the wcsprm struct.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 6.1.1.1 2018/10/19 08:36:15 mcalabre Exp mcalabre $
d1062 1
a1062 1
*     (Given) ... those associated with the CROTAi keywords.  Although these
d1068 1
a1068 1
*     and CROTAi keywords are present in the header:
d1078 1
a1078 1
*       zero.  If no CDi_ja (or CROTAi) keywords are present, then the
d1084 1
a1084 1
*       with CDELTia and CROTAi which are to be ignored.
d1086 1
a1086 1
*     - Bit 2: CROTAi is present.
d1088 1
a1088 1
*       In the AIPS convention, CROTAi may only be
d1091 1
a1091 1
*       CDELTia; any other CROTAi keywords are ignored.
d1093 1
a1093 1
*       CROTAi may not formally co-exist with PCi_ja.
d1095 1
a1095 1
*       CROTAi and CDELTia may formally co-exist with CDi_ja but if so are to
d1098 1
a1098 1
*     CDi_ja and CROTAi keywords, if found, are to be stored in the
d1107 1
a1107 1
*     - Whenever a CROTAi keyword is encountered: altlin |= 4;
d1117 1
a1117 1
*     If CROTAi are present but none is associated with the latitude axis
d1363 1
a1363 1
*     between DATE-BEG and DATE-END, in units of TIMEUNIT.
d1557 3
d1576 2
a1669 1
#define wtbarr wtbarr_s		/* See prologue of wtbarr.h.                */
d1767 1
a1767 1
  double *crota;		/* CROTAi keyvalues for each coord axis.    */
d1771 1
a1771 1
				/*   Bit 2: CROTAi is present.              */
a1917 1
#undef wtbarr
@


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: wcs.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
d59 5
d1184 81
a1264 3
*   char dateavg[72]
*     (Given, auxiliary) The date of a representative mid-point of the
*     observation in ISO format, yyyy-mm-ddThh:mm:ss.
d1267 1
a1267 1
*     wcsprm::dateavg is changed.
d1270 2
a1271 2
*     (Given, auxiliary) The date of the start of the observation unless
*     otherwise explained in the comment field of the DATE-OBS keyword, in
d1277 31
a1307 4
*   double equinox
*     (Given, auxiliary) The equinox associated with dynamical equatorial or
*     ecliptic coordinate systems, EQUINOXa (or EPOCH in older headers).  Not
*     applicable to ICRS equatorial or ecliptic coordinates.
d1310 1
a1310 1
*     wcsprm::equinox is changed.
d1313 2
a1314 2
*     (Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-AVG,
*     corresponding to DATE-AVG.
d1319 73
a1391 3
*   double mjdobs
*     (Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-OBS,
*     corresponding to DATE-OBS.
d1394 1
a1394 1
*     wcsprm::mjdobs is changed.
d1396 1
a1396 1
*   double obsgeo[3]
d1398 4
a1401 1
*     reference frame, OBSGEO-X, OBSGEO-Y, OBSGEO-Z [m].
d1406 7
d1420 8
a1470 9
*   char wcsname[72]
*     (Given, auxiliary) The name given to the coordinate representation,
*     WCSNAMEa.  This variable accomodates the longest allowed string-valued
*     FITS keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::wcsname is changed.
*
d1610 4
a1654 51
* wtbarr struct - Extraction of coordinate lookup tables from BINTABLE
* --------------------------------------------------------------------
* Function wcstab(), which is invoked automatically by wcspih(), sets up an
* array of wtbarr structs to assist in extracting coordinate lookup tables
* from a binary table extension (BINTABLE) and copying them into the tabprm
* structs stored in wcsprm.  Refer to the usage notes for wcspih() and
* wcstab() in wcshdr.h, and also the prologue to tab.h.
*
* For C++ usage, because of a name space conflict with the wtbarr typedef
* defined in CFITSIO header fitsio.h, the wtbarr struct is renamed to wtbarr_s
* by preprocessor macro substitution with scope limited to wcs.h itself.
*
*   int i
*     (Given) Image axis number.
*
*   int m
*     (Given) wcstab array axis number for index vectors.
*
*   int kind
*     (Given) Character identifying the wcstab array type:
*       - c: coordinate array,
*       - i: index vector.
*
*   char extnam[72]
*     (Given) EXTNAME identifying the binary table extension.
*
*   int extver
*     (Given) EXTVER identifying the binary table extension.
*
*   int extlev
*     (Given) EXTLEV identifying the binary table extension.
*
*   char ttype[72]
*     (Given) TTYPEn identifying the column of the binary table that contains
*     the wcstab array.
*
*   long row
*     (Given) Table row number.
*
*   int ndim
*     (Given) Expected dimensionality of the wcstab array.
*
*   int *dimlen
*     (Given) Address of the first element of an array of int of length ndim
*     into which the wcstab array axis lengths are to be written.
*
*   double **arrayp
*     (Given) Pointer to an array of double which is to be allocated by the
*     user and into which the wcstab array is to be written.
*
*
a1732 21
				/* For extracting wcstab arrays.  Matches   */
				/* the wtbarr typedef defined in CFITSIO    */
				/* header fitsio.h.                         */
#ifdef __cplusplus
#define wtbarr wtbarr_s		/* See prologue above.                      */
#endif
struct wtbarr {
  int  i;			/* Image axis number.                       */
  int  m;			/* Array axis number for index vectors.     */
  int  kind;			/* wcstab array type.                       */
  char extnam[72];		/* EXTNAME of binary table extension.       */
  int  extver;			/* EXTVER  of binary table extension.       */
  int  extlev;			/* EXTLEV  of binary table extension.       */
  char ttype[72];		/* TTYPEn of column containing the array.   */
  long row;			/* Table row number.                        */
  int  ndim;			/* Expected wcstab array dimensionality.    */
  int  *dimlen;			/* Where to write the array axis lengths.   */
  double **arrayp;		/* Where to write the address of the array  */
				/* allocated to store the wcstab array.     */
};

d1774 2
a1775 1
  /* Auxiliary coordinate system information, not used by WCSLIB.           */
d1779 1
a1779 1

d1783 23
a1805 2
  char   dateavg[72];
  char   dateobs[72];
a1806 4
  double mjdavg;
  double mjdobs;
  double obsgeo[3];
  char   radesys[72];
a1812 1
  char   wcsname[72];
d1821 1
a1828 1
  void   *padding;		/* (Dummy inserted for alignment purposes.) */
d1830 1
a1830 1
  struct linprm lin;		/* Linear    transformation parameters.     */
d1832 5
a1836 1
  struct spcprm spc;		/* Spectral  transformation parameters.     */
d1842 1
a1842 1
  /* Private - the remainder are for memory management.                     */
a1843 1
  void   *m_padding;
d1852 1
a1852 1
  double *m_crder, *m_csyer;
a1917 1
#undef wtbarr
@


5.20.1.1
log
@WCSLIB 5.20 development branch.
@
text
@d25 1
a25 1
  $Id: wcs.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).  Extracted the
definition of the wtbarr struct into a separate header file, wtbarr.h, in
order to reduce the number of irrelevant warnings generated by -Wpadded.  Code
that needs to access members of the struct must now include wtbarr.h (or
wcslib.h).
@
text
@d25 1
a25 1
  $Id: wcs.h,v 5.20.1.1 2018/10/05 05:33:33 mcalabre Exp mcalabre $
a58 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)
d1179 3
a1181 3
*   double *czphs
*     (Given, auxiliary) Address of the first element of an array of double
*     recording the time at the zero point of a phase axis, CZPHSia.
d1184 1
a1184 79
*     wcsprm::czphs is changed.
*
*   double *cperi
*     (Given, auxiliary) Address of the first element of an array of double
*     recording the period of a phase axis, CPERIia.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::cperi is changed.
*
*   char wcsname[72]
*     (Given, auxiliary) The name given to the coordinate representation,
*     WCSNAMEa.  This variable accomodates the longest allowed string-valued
*     FITS keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::wcsname is changed.
*
*   char timesys[72]
*     (Given, auxiliary) TIMESYS keyvalue, being the time scale (UTC, TAI,
*     etc.) in which all other time-related auxiliary header values are
*     recorded.  Also defines the time scale for an image axis with CTYPEia
*     set to 'TIME'.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timesys is changed.
*
*   char trefpos[72]
*     (Given, auxiliary) TREFPOS keyvalue, being the location in space where
*     the recorded time is valid.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::trefpos is changed.
*
*   char trefdir[72]
*     (Given, auxiliary) TREFDIR keyvalue, being the reference direction used
*     in calculating a pathlength delay.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::trefdir is changed.
*
*   char plephem[72]
*     (Given, auxiliary) PLEPHEM keyvalue, being the Solar System ephemeris
*     used for calculating a pathlength delay.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::plephem is changed.
*
*   char timeunit[72]
*     (Given, auxiliary) TIMEUNIT keyvalue, being the time units in which
*     the following header values are expressed: TSTART, TSTOP, TIMEOFFS,
*     TIMSYER, TIMRDER, TIMEDEL.  It also provides the default value for
*     CUNITia for time axes.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timeunit is changed.
*
*   char dateref[72]
*     (Given, auxiliary) DATEREF keyvalue, being the date of a reference epoch
*     relative to which other time measurements refer.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::dateref is changed.
*
*   double mjdref[2]
*     (Given, auxiliary) MJDREF keyvalue, equivalent to DATEREF expressed as
*     a Modified Julian Date (MJD = JD - 2400000.5).  The value is given as
*     the sum of the two-element vector, allowing increased precision.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdref is changed.
*
*   double timeoffs
*     (Given, auxiliary) TIMEOFFS keyvalue, being a time offset, which may be
*     used, for example, to provide a uniform clock correction for times
*     referenced to DATEREF.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timeoffs is changed.
d1187 2
a1188 2
*     (Given, auxiliary) DATE-OBS keyvalue, being the date at the start of the
*     observation unless otherwise explained in the DATE-OBS keycomment, in
d1194 4
a1197 3
*   char datebeg[72]
*     (Given, auxiliary) DATE-BEG keyvalue, being the date at the start of the
*     observation in ISO format, yyyy-mm-ddThh:mm:ss.
d1200 1
a1200 1
*     wcsprm::datebeg is changed.
d1202 3
a1204 3
*   char dateavg[72]
*     (Given, auxiliary) DATE-AVG keyvalue, being the date at a representative
*     mid-point of the observation in ISO format, yyyy-mm-ddThh:mm:ss.
d1207 1
a1207 8
*     wcsprm::dateavg is changed.
*
*   char dateend[72]
*     (Given, auxiliary) DATE-END keyvalue, baing the date at the end of the
*     observation in ISO format, yyyy-mm-ddThh:mm:ss.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::dateend is changed.
d1210 2
a1211 2
*     (Given, auxiliary) MJD-OBS keyvalue, equivalent to DATE-OBS expressed
*     as a Modified Julian Date (MJD = JD - 2400000.5).
d1216 1
a1216 92
*   double mjdbeg
*     (Given, auxiliary) MJD-BEG keyvalue, equivalent to DATE-BEG expressed
*     as a Modified Julian Date (MJD = JD - 2400000.5).
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdbeg is changed.
*
*   double mjdavg
*     (Given, auxiliary) MJD-AVG keyvalue, equivalent to DATE-AVG expressed
*     as a Modified Julian Date (MJD = JD - 2400000.5).
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdavg is changed.
*
*   double mjdend
*     (Given, auxiliary) MJD-END keyvalue, equivalent to DATE-END expressed
*     as a Modified Julian Date (MJD = JD - 2400000.5).
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdend is changed.
*
*   double jepoch
*     (Given, auxiliary) JEPOCH keyvalue, equivalent to DATE-OBS expressed
*     as a Julian epoch.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::jepoch is changed.
*
*   double bepoch
*     (Given, auxiliary) BEPOCH keyvalue, equivalent to DATE-OBS expressed
*     as a Besselian epoch
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::bepoch is changed.
*
*   double tstart
*     (Given, auxiliary) TSTART keyvalue, equivalent to DATE-BEG expressed
*     as a time in units of TIMEUNIT relative to DATEREF+TIMEOFFS.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::tstart is changed.
*
*   double tstop
*     (Given, auxiliary) TSTOP keyvalue, equivalent to DATE-END expressed
*     as a time in units of TIMEUNIT relative to DATEREF+TIMEOFFS.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::tstop is changed.
*
*   double xposure
*     (Given, auxiliary) XPOSURE keyvalue, being the effective exposure time
*     in units of TIMEUNIT.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::xposure is changed.
*
*   double telapse
*     (Given, auxiliary) TELAPSE keyvalue, equivalent to the elapsed time
*     between DATE-BEG and DATE-END, in units of TIMEUNIT, 
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::telapse is changed.
*
*   double timsyer
*     (Given, auxiliary) TIMSYER keyvalue, being the absolute error of the
*     time values, in units of TIMEUNIT.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timsyer is changed.
*
*   double timrder
*     (Given, auxiliary) TIMRDER keyvalue, being the accuracy of time stamps
*     relative to each other, in units of TIMEUNIT.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timrder is changed.
*
*   double timedel
*     (Given, auxiliary) TIMEDEL keyvalue, being the resolution of the time
*     stamps.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timedel is changed.
*
*   double timepixr
*     (Given, auxiliary) TIMEPIXR keyvalue, being the relative position of the
*     time stamps in binned time intervals, a value between 0.0 and 1.0.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::timepixr is changed.
*
*   double obsgeo[6]
d1218 1
a1218 4
*     reference frame.  The first three give ITRS Cartesian coordinates
*     OBSGEO-X [m],   OBSGEO-Y [m],   OBSGEO-Z [m], and the second three give
*     OBSGEO-L [deg], OBSGEO-B [deg], OBSGEO-H [m], which are related through
*     a standard transformation.
a1222 7
*   char obsorbit[72]
*     (Given, auxiliary) OBSORBIT keyvalue, being the URI, URL, or name of an
*     orbit ephemeris file giving spacecraft coordinates relating to TREFPOS.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::obsorbit is changed.
*
a1229 8
*   double equinox
*     (Given, auxiliary) The equinox associated with dynamical equatorial or
*     ecliptic coordinate systems, EQUINOXa (or EPOCH in older headers).  Not
*     applicable to ICRS equatorial or ecliptic coordinates.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::equinox is changed.
*
d1273 9
a1420 4
*   double *m_czphs
*     (For internal use only.)
*   double *m_cperi
*     (For internal use only.)
d1462 51
d1591 21
d1653 1
a1653 2
  /* Auxiliary coordinate system information, not used by WCSLIB.  Refer to */
  /* the prologue comments above for a brief explanation of these values.   */
d1657 1
a1657 1
				/* Auxiliary coordinate axis information.   */
d1661 6
a1666 22
  double *czphs;
  double *cperi;

  char   wcsname[72];
				/* Time reference system and measurement.   */
  char   timesys[72], trefpos[72], trefdir[72], plephem[72];
  char   timeunit[72];
  char   dateref[72];
  double mjdref[2];
  double timeoffs;
				/* Data timestamps and durations.           */
  char   dateobs[72], datebeg[72], dateavg[72], dateend[72];
  double mjdobs, mjdbeg, mjdavg, mjdend;
  double jepoch, bepoch;
  double tstart, tstop;
  double xposure, telapse;
				/* Timing accuracy.                         */
  double timsyer, timrder;
  double timedel, timepixr;
				/* Spatial & celestial reference frame.     */
  double obsgeo[6];
  char   obsorbit[72];
a1667 1
  double equinox;
d1674 1
a1682 1
  /*------------------------------------------------------------------------*/
d1690 1
d1692 1
a1692 1
  struct linprm lin;		/*    Linear transformation parameters.     */
d1694 1
a1694 5
  struct spcprm spc;		/*  Spectral transformation parameters.     */

  /*------------------------------------------------------------------------*/
  /*             THE REMAINDER OF THE WCSPRM STRUCT IS PRIVATE.             */
  /*------------------------------------------------------------------------*/
d1700 1
a1700 1
  /* Memory management.                                                     */
d1702 1
d1711 1
a1711 1
  double *m_crder, *m_csyer, *m_czphs, *m_cperi;
d1777 1
@


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: wcs.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: wcs.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: wcs.h,v 5.17.1.4 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: wcs.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: wcs.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
d65 6
a70 6
* wcsnpv(), wcsnps(), wcsini(), wcssub(), and wcsfree() are provided to manage
* the wcsprm struct and another, wcsprt(), prints its contents.  Refer to the
* description of the wcsprm struct for an explanation of the anticipated usage
* of these routines.  wcscopy(), which does a deep copy of one wcsprm struct
* to another, is defined as a preprocessor macro function that invokes
* wcssub().
d124 4
a127 3
* wcsnpv() changes the value of NPVMAX (default 64).  This global variable
* controls the number of pvcard structs, for holding PVi_ma keyvalues, that
* wcsini() should allocate space for.
d132 2
a133 1
*   n         int       Value of NPVMAX; ignored if < 0.
d141 1
a141 1
* wcsnps() changes the values of NPSMAX (default 8).  This global variable
d143 2
a144 1
* wcsini() should allocate space for.
d149 2
a150 1
*   n         int       Value of NPSMAX; ignored if < 0.
d158 17
a174 9
* wcsini() optionally allocates memory for arrays in a wcsprm struct and sets
* all members of the struct to default values.  Memory is allocated for up to
* NPVMAX PVi_ma keywords or NPSMAX PSi_ma keywords per WCS representation.
* These may be changed via wcsnpv() and wcsnps() before wcsini() is called.
*
* PLEASE NOTE: every wcsprm struct should be initialized by wcsini(), possibly
* repeatedly.  On the first invokation, and only the first invokation,
* wcsprm::flag must be set to -1 to initialize memory management, regardless
* of whether wcsini() will actually be used to allocate memory.
d200 17
d230 1
a230 1
* struct.  It does a deep copy, using wcsini() to allocate memory for its
d250 1
a250 1
* using the defaults set by wcsini() which produce a simple, unnamed, linear
d273 1
a273 1
*                       the defaults set by wcsini().  They can be changed
d411 2
a412 2
* wcsfree() frees memory allocated for the wcsprm arrays by wcsini() and/or
* wcsset().  wcsini() records the memory it allocates and wcsfree() will only
d416 1
a416 1
* initialized by wcsini().
d848 1
a848 1
* While the addresses of the arrays themselves may be set by wcsini() if it
d859 1
a859 1
* determine the number of coordinate axes.  It would then use wcsini() to
d899 1
a899 1
*     PLEASE NOTE: flag should be set to -1 when wcsini() is called for the
d907 1
a907 1
*     If wcsini() is used to initialize the linprm struct (as would normally
d1000 1
a1000 1
*     lonpole and latpole may be left to default to values set by wcsini()
d1003 1
a1003 1
*     reused without resetting them, whether directly or via wcsini(), they
d1018 1
a1018 1
*     npvmax will be set by wcsini() if it allocates memory for wcsprm::pv[],
d1040 1
a1040 1
*     npsmax will be set by wcsini() if it allocates memory for wcsprm::ps[],
d1725 3
@


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


5.17.1.2
log
@Added new function wcsinit(), with disini() now a thin wrapper over it.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 5.17.1.1 2017/09/18 08:45:59 mcalabre Exp mcalabre $
d65 6
a70 6
* wcsnpv(), wcsnps(), wcsini(), wcsinit(), wcssub(), and wcsfree() are
* provided to manage the wcsprm struct and another, wcsprt(), prints its
* contents.  Refer to the description of the wcsprm struct for an explanation
* of the anticipated usage of these routines.  wcscopy(), which does a deep
* copy of one wcsprm struct to another, is defined as a preprocessor macro
* function that invokes wcssub().
d126 1
a126 2
* wcsini() should allocate space for.  It is also used by wcsinit() as the
* default value of npvmax.
d141 1
a141 2
* wcsini() should allocate space for.  It is also used by wcsinit() as the
* default value of npsmax.
d154 9
a162 17
* wcsini() is a thin wrapper on wcsinit().  It invokes it with npvmax,
* npsmax, and ndpmax set to -1 which causes it to use the values of the
* global variables NDPMAX, NPSMAX, and NDPMAX.  It is thereby potentially
* thread-unsafe if these variables are altered dynamically via wcsnpv(),
* wcsnps(), and disndp().  Use wcsinit() for a thread-safe alternative in
* this case.
*
*
* wcsinit() - Default constructor for the wcsprm struct
* -----------------------------------------------------
* wcsinit() optionally allocates memory for arrays in a wcsprm struct and sets
* all members of the struct to default values.
*
* PLEASE NOTE: every wcsprm struct should be initialized by wcsinit(),
* possibly repeatedly.  On the first invokation, and only the first
* invokation, wcsprm::flag must be set to -1 to initialize memory management,
* regardless of whether wcsinit() will actually be used to allocate memory.
a187 17
* Given:
*   npvmax    int       The number of PVi_ma keywords to allocate space for.
*                       If set to -1, the value of the global variable NPVMAX
*                       will be used.  This is potentially thread-unsafe if
*                       wcsnpv() is being used dynamically to alter its value.
*
*   npsmax    int       The number of PSi_ma keywords to allocate space for.
*                       If set to -1, the value of the global variable NPSMAX
*                       will be used.  This is potentially thread-unsafe if
*                       wcsnps() is being used dynamically to alter its value.
*
*   ndpmax    int       The number of DPja or DQia keywords to allocate space
*                       for.  If set to -1, the value of the global variable
*                       NDPMAX will be used.  This is potentially
*                       thread-unsafe if disndp() is being used dynamically to
*                       alter its value.
*
d201 1
a201 1
* struct.  It does a deep copy, using wcsinit() to allocate memory for its
d221 1
a221 1
* using the defaults set by wcsinit() which produce a simple, unnamed, linear
d244 1
a244 1
*                       the defaults set by wcsinit().  They can be changed
d382 2
a383 2
* wcsfree() frees memory allocated for the wcsprm arrays by wcsinit() and/or
* wcsset().  wcsinit() records the memory it allocates and wcsfree() will only
d387 1
a387 1
* initialized by wcsinit().
d819 1
a819 1
* While the addresses of the arrays themselves may be set by wcsinit() if it
d830 1
a830 1
* determine the number of coordinate axes.  It would then use wcsinit() to
d870 1
a870 1
*     PLEASE NOTE: flag should be set to -1 when wcsinit() is called for the
d878 1
a878 1
*     If wcsinit() is used to initialize the linprm struct (as would normally
d971 1
a971 1
*     lonpole and latpole may be left to default to values set by wcsinit()
d974 1
a974 1
*     reused without resetting them, whether directly or via wcsinit(), they
d989 1
a989 1
*     npvmax will be set by wcsinit() if it allocates memory for wcsprm::pv[],
d1011 1
a1011 1
*     npsmax will be set by wcsinit() if it allocates memory for wcsprm::ps[],
a1695 3

int wcsinit(int alloc, int naxis, struct wcsprm *wcs, int npvmax, int npsmax,
            int ndpmax);
@


5.17.1.3
log
@Minor changes to the prologue comments for wcsnpv() and wcsnps().
@
text
@d25 1
a25 1
  $Id: wcs.h,v 5.17.1.2 2017/12/05 07:42:06 mcalabre Exp mcalabre $
d124 4
a127 4
* wcsnpv() sets or gets the value of NPVMAX (default 64).  This global
* variable controls the number of pvcard structs, for holding PVi_ma
* keyvalues, that wcsini() should allocate space for.  It is also used by
* wcsinit() as the default value of npvmax.
d132 1
a132 2
*   n         int       Value of NPVMAX; ignored if < 0.  Use a value less
*                       than zero to get the current value.
d140 1
a140 1
* wcsnps() sets or gets the value of NPSMAX (default 8).  This global variable
d148 1
a148 2
*   n         int       Value of NPSMAX; ignored if < 0.  Use a value less
*                       than zero to get the current value.
@


5.17.1.4
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2018, Mark Calabretta
d25 1
a25 1
  $Id: wcs.h,v 5.17.1.3 2017/12/05 23:33:23 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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.h,v 5.12.1.2 2016/01/25 05:17:04 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: wcs.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: wcs.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
@


5.12.1.1
log
@WCSLIB 5.12 development branch.
@
text
@d25 1
a25 1
  $Id: wcs.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: wcs.h,v 5.12.1.1 2015/11/15 02:16:14 mcalabre Exp mcalabre $
@


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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.h,v 5.6.1.2 2015/06/16 07:45:15 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: wcs.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: wcs.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
d203 3
a205 1
* struct is extracted; a call to wcsset() is required to set up the remainder.
d210 5
a214 3
* the PCi_ja matrix of the original image must not contain non-zero
* off-diagonal terms that associate any of the subimage axes with any of the
* non-subimage axes.
@


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


5.6.1.2
log
@Augmented the usage notes for wcssub().
@
text
@d25 1
a25 1
  $Id: wcs.h,v 5.6.1.1 2015/06/14 07:14:44 mcalabre Exp mcalabre $
d203 1
a203 3
* struct is extracted.  Consequently, wcsset() need not have been, and won't
* be invoked on the struct from which the subimage is extracted.  A call to
* wcsset() is required to set up the subimage struct.
d208 3
a210 5
* the linear transformation matrix of the original image must not contain
* non-zero off-diagonal terms that associate any of the subimage axes with any
* of the non-subimage axes.  Likewise, if any distortions are associated with
* the subimage axes, they must not depend on any of the axes that are not
* being extracted.
@


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: wcs.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: wcs.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: wcs.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.
d35 29
a63 7
* These routines implement the FITS World Coordinate System (WCS) standard
* which defines methods to be used for computing world coordinates from image
* pixel coordinates, and vice versa.  They are based on the wcsprm struct
* which contains all information needed for the computations.  The struct
* contains some members that must be set by the user, and others that are
* maintained by these routines, somewhat like a C++ class but with no
* encapsulation.
@


5.4.1.1
log
@WCSLIB 5.4 development branch.
@
text
@d25 1
a25 1
  $Id: wcs.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 added references to Papers IV,
V, and VI.
@
text
@d25 1
a25 1
  $Id: wcs.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.
d47 7
a53 29
* Routines in this suite implement the FITS World Coordinate System (WCS)
* standard which defines methods to be used for computing world coordinates
* from image pixel coordinates, and vice versa.  The standard, and proposed
* extensions for handling distortions, are described 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
=
=   "Mapping on the HEALPix grid",
=   Calabretta, M.R., & Roukema, B.F. 2007, MNRAS, 381, 865 (WCS Paper V)
=
=   "Representing the 'Butterfly' Projection in FITS -- Projection Code XPH",
=   Calabretta, M.R., & Lowe, S.R. 2013, PASA, 30, e050 (WCS Paper VI)
*
* These routines are based on the wcsprm struct which contains all information
* needed for the computations.  The struct contains some members that must be
* set by the user, and others that are maintained by these routines, somewhat
* like a C++ class but with no encapsulation.
@


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: wcs.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: wcs.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: wcs.h,v 5.1.1.4 2015/04/13 11:46:15 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: wcs.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: wcs.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
d55 2
a56 2
* Three routines, wcsini(), wcssub(), and wcsfree() are provided to manage the
* wcsprm struct and another, wcsprt(), to prints its contents.  Refer to the
d112 30
a187 30
* wcsnpv() - Memory allocation for PVi_ma
* ---------------------------------------
* wcsnpv() changes the value of NPVMAX (default 64).  This global variable
* controls the number of PVi_ma keywords that wcsini() should allocate space
* for.
*
* PLEASE NOTE: This function is not thread-safe.
*
* Given:
*   n         int       Value of NPVMAX; ignored if < 0.
*
* Function return value:
*             int       Current value of NPVMAX.
*
*
* wcsnps() - Memory allocation for PSi_ma
* ---------------------------------------
* wcsnps() changes the values of NPSMAX (default 8).  This global variable
* controls the number of PSi_ma keywords that wcsini() should allocate space
* for.
*
* PLEASE NOTE: This function is not thread-safe.
*
* Given:
*   n         int       Value of NPSMAX; ignored if < 0.
*
* Function return value:
*             int       Current value of NPSMAX.
*
*
d805 9
a813 5
* Some of the former are not actually required for transforming coordinates.
* These are described as "auxiliary"; the struct simply provides a place to
* store them, though they may be used by wcshdo() in constructing a FITS
* header from a wcsprm struct.  Some of the returned values are supplied for
* informational purposes and others are for internal use only as indicated.
d979 2
a980 3
*     (Given or returned) Address of the first element of an array of length
*     npvmax of pvcard structs.  Set by wcsini() if it allocates memory for
*     pv[], otherwise it must be set by the user.  See also wcsnpv().
d1001 2
a1002 3
*     (Given or returned) Address of the first element of an array of length
*     npsmax of pscard structs.  Set by wcsini() if it allocates memory for
*     ps[], otherwise it must be set by the user.  See also wcsnps().
d1384 1
a1384 1
* pscard struct - Store for PSi_ma keyrecords
d1386 1
a1386 1
* The pscard struct is used to pass the parsed contents of PSi_ma keyrecords
d1392 2
a1393 1
*     (Given) Axis number (1-relative), as in the FITS PSi_ma keyword.
d1396 1
a1396 1
*     (Given) Parameter number (non-negative), as in the FITS PSi_ma keyword.
d1398 1
a1398 1
*   char value[72]
d1402 1
a1402 1
* pvcard struct - Store for PVi_ma keyrecords
d1404 1
a1404 1
* The pvcard struct is used to pass the parsed contents of PVi_ma keyrecords
d1410 1
a1410 2
*     (Given) Axis number (1-relative), as in the FITS PVi_ma keyword.  If
*     i == 0, wcsset() will replace it with the latitude axis number.
d1413 1
a1413 1
*     (Given) Parameter number (non-negative), as in the FITS PVi_ma keyword.
d1415 1
a1415 1
*   double value
d1535 3
d1544 3
@


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


5.1.1.2
log
@Rearrangement of, and minor amendments to prologue text.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 5.1.1.1 2015/04/07 11:01:10 mcalabre Exp mcalabre $
a111 30
* wcsnpv() - Memory allocation for PVi_ma
* ---------------------------------------
* wcsnpv() changes the value of NPVMAX (default 64).  This global variable
* controls the number of pvcard structs, for holding PVi_ma keyvalues, that
* wcsini() should allocate space for.
*
* PLEASE NOTE: This function is not thread-safe.
*
* Given:
*   n         int       Value of NPVMAX; ignored if < 0.
*
* Function return value:
*             int       Current value of NPVMAX.
*
*
* wcsnps() - Memory allocation for PSi_ma
* ---------------------------------------
* wcsnps() changes the values of NPSMAX (default 8).  This global variable
* controls the number of pscard structs, for holding PSi_ma keyvalues, that
* wcsini() should allocate space for.
*
* PLEASE NOTE: This function is not thread-safe.
*
* Given:
*   n         int       Value of NPSMAX; ignored if < 0.
*
* Function return value:
*             int       Current value of NPSMAX.
*
*
d158 30
d805 5
a809 9
* While the addresses of the arrays themselves may be set by wcsini() if it
* (optionally) allocates memory, their contents must be set by the user.
*
* Some parameters that are given are not actually required for transforming
* coordinates.  These are described as "auxiliary"; the struct simply provides
* a place to store them, though they may be used by wcshdo() in constructing a
* FITS header from a wcsprm struct.  Some of the returned values are supplied
* for informational purposes and others are for internal use only as
* indicated.
d975 3
a977 2
*     (Given) Address of the first element of an array of length npvmax of
*     pvcard structs.
d998 3
a1000 2
*     (Given) Address of the first element of an array of length npsmax of
*     pscard structs.
d1382 1
a1382 1
* pvcard struct - Store for PVi_ma keyrecords
d1384 1
a1384 1
* The pvcard struct is used to pass the parsed contents of PVi_ma keyrecords
d1390 1
a1390 2
*     (Given) Axis number (1-relative), as in the FITS PVi_ma keyword.  If
*     i == 0, wcsset() will replace it with the latitude axis number.
d1393 1
a1393 1
*     (Given) Parameter number (non-negative), as in the FITS PVi_ma keyword.
d1395 1
a1395 1
*   double value
d1399 1
a1399 1
* pscard struct - Store for PSi_ma keyrecords
d1401 1
a1401 1
* The pscard struct is used to pass the parsed contents of PSi_ma keyrecords
d1407 2
a1408 1
*     (Given) Axis number (1-relative), as in the FITS PSi_ma keyword.
d1411 1
a1411 1
*     (Given) Parameter number (non-negative), as in the FITS PSi_ma keyword.
d1413 1
a1413 1
*   char value[72]
@


5.1.1.3
log
@Mention wcsnpv() and wcsnps() in the summary of wcs routines.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 5.1.1.2 2015/04/13 08:27:21 mcalabre Exp mcalabre $
d55 2
a56 2
* wcsnpv(), wcsnps(), wcsini(), wcssub(), and wcsfree() are provided to manage
* the wcsprm struct and another, wcsprt(), prints its contents.  Refer to the
@


5.1.1.4
log
@Added PVLEN and PSLEN, not actually used by the Fortran wrappers, but they
could be.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 5.1.1.3 2015/04/13 09:36:30 mcalabre Exp mcalabre $
a1534 3
/* Size of the pvcard struct in int units, used by the Fortran wrappers. */
#define PVLEN (sizeof(struct pvcard)/sizeof(int))

a1540 3

/* Size of the pscard struct in int units, used by the Fortran wrappers. */
#define PSLEN (sizeof(struct pscard)/sizeof(int))
@


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: wcs.h,v 4.25.1.6 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: wcs.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: wcs.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
d82 2
d771 29
d842 5
a846 1
*       - wcsprm::altlin.
d1074 3
d1086 3
d1096 3
d1106 3
d1117 3
d1123 4
d1131 3
d1137 4
d1146 3
d1154 3
d1160 4
d1168 3
d1175 3
d1182 3
d1187 5
a1191 1
*     SPECSYSa, and ...
d1193 1
a1193 1
*     (Given, auxiliary) ... the actual frame in which there is no
d1196 4
d1205 3
d1209 5
a1213 1
*     (Given, auxiliary) The redshift, ZSOURCEa, of the source, and ...
d1215 5
a1219 2
*     (Given, auxiliary) ... the spectral reference frame (standard of rest)
*     in which this was measured, SSYSSRCa.
d1225 3
d1234 3
d1339 1
a1339 1
*     (Returned) If enabled, when an error status is returned this struct
a1479 2
#include "tab.h"
#include "wcserr.h"
d1507 1
a1507 1
				   axis types. */
d1509 2
a1510 2
  WCSERR_BAD_COORD_TRANS =  6,	/* Invalid coordinate transformation
				   parameters. */
d1512 1
a1512 1
				   parameters. */
d1645 1
a1645 1
  /* Error handling                                                         */
d1704 2
@


4.25.1.1
log
@WCSLIB 4.25 development branch.
@
text
@d25 1
a25 1
  $Id: wcs.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: wcs.h,v 4.25.1.1 2014/12/14 14:32:45 mcalabre Exp mcalabre $
@


4.25.1.3
log
@Added function wcslib_version() to return the WCSLIB version number.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.25.1.2 2015/01/06 01:01:06 mcalabre Exp mcalabre $
a81 2
* wcslib_version() returns the WCSLIB version number.
*
a768 29
* wcslib_version() - WCSLIB version number
* ----------------------------------------
* wcslib_version() returns the WCSLIB version number.
*
* The major version number changes when the ABI changes or when the license
* conditions change.  ABI changes typically result from a change to the
* contents of one of the structs.  The major version number is used to
* distinguish between incompatible versions of the sharable library.
*
* The minor version number changes with new functionality or bug fixes that do
* not involve a change in the ABI.
*
* The auxiliary version number (which is often absent) signals changes to the
* documentation, test suite, build procedures, or any other change that does
* not affect the compiled library.
*
* Returned:
*   vers[3]   int[3]    The broken-down version number:
*                         0: Major version number.
*                         1: Minor version number.
*                         2: Auxiliary version number (zero if absent).
*                       May be given as a null pointer if not required.
*
* Function return value:
*             char*     A null-terminated, statically allocated string
*                       containing the version number in the usual form, i.e.
*                       "<major>.<minor>.<auxiliary>".
*
*
a1601 2

const char* wcslib_version(int vers[3]);
@


4.25.1.4
log
@No need to include tab.h nor wcserr.h.  Prologue and other wording tweaks.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.25.1.3 2015/03/05 08:20:35 mcalabre Exp mcalabre $
d1266 1
a1266 1
*     (Returned) If enabled, when an error status is returned, this struct
d1407 2
d1436 1
a1436 1
				   axis type. */
d1438 2
a1439 2
  WCSERR_BAD_COORD_TRANS =  6,	/* Unrecognised coordinate transformation
				   parameter. */
d1441 1
a1441 1
				   parameter. */
d1574 1
a1574 1
  /* Error handling, if enabled.                                            */
@


4.25.1.5
log
@Tweaks to prologue.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.25.1.4 2015/04/03 01:41:19 mcalabre Exp mcalabre $
d842 1
a842 5
*       - wcsprm::altlin,
*       - wcsprm::ntab,
*       - wcsprm::nwtb,
*       - wcsprm::tab,
*       - wcsprm::wtb.
a1069 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::velref is changed.
*
a1078 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::alt is changed.
*
a1085 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::colnum is changed.
*
a1092 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::colax is changed.
*
a1100 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::cname is changed.
*
a1103 4
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::crder is changed.
*
a1107 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::csyer is changed.
*
a1110 4
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::dateavg is changed.
*
a1115 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::dateobs is changed.
*
a1120 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::equinox is changed.
*
a1123 4
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdavg is changed.
*
a1127 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::mjdobs is changed.
*
a1131 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::obsgeo is changed.
*
a1135 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::radesys is changed.
*
d1138 1
a1138 5
*     SPECSYSa.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::specsys is changed.
*
d1140 1
a1140 1
*     (Given, auxiliary) The spectral reference frame in which there is no
a1142 4
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::ssysobs is changed.
*
a1147 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::velosys is changed.
*
d1149 1
a1149 5
*     (Given, auxiliary) The redshift, ZSOURCEa, of the source.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::zsource is changed.
*
d1151 2
a1152 5
*     (Given, auxiliary) The spectral reference frame (standard of rest),
*     SSYSSRCa, in which wcsprm::zsource was measured.
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::ssyssrc is changed.
a1157 3
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::velangl is changed.
*
a1162 3
*
*     It is not necessary to reset the wcsprm struct (via wcsset()) when
*     wcsprm::wcsname is changed.
@


4.25.1.6
log
@Americanized spelling.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.25.1.5 2015/04/05 06:01:11 mcalabre Exp mcalabre $
d1509 1
a1509 1
  WCSERR_BAD_COORD_TRANS =  6,	/* Unrecognized coordinate transformation
@


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: wcs.h,v 4.23.1.2 2014/05/22 10:53:09 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: wcs.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: wcs.h,v 4.22.1.2 2014/05/10 14:30:40 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.23 - C routines that implement the FITS World Coordinate System
d337 5
d1576 2
a1577 2
int wcscompare(int cmp, const struct wcsprm *wcs1, const struct wcsprm *wcs2,
               int *equal);
@


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


4.23.1.2
log
@Changed API to wcscompare() to allow a tolerance to be specified for
floating-point comparisons.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.23.1.1 2014/05/13 05:53:49 mcalabre Exp mcalabre $
a336 5
*   tol       double    Tolerance for comparison of floating-point values.
*                       For example, for tol == 1e-6, all floating-point
*                       values in the structs must be equal to the first 6
*                       decimal places.  A value of 0 implies exact equality.
*
d1571 2
a1572 2
int wcscompare(int cmp, double tol, const struct wcsprm *wcs1,
               const struct wcsprm *wcs2, int *equal);
@


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: wcs.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
d315 37
d526 1
a526 1
*                         1+: A bit mask indicating invalid pixel coordinate
d592 1
a592 1
*                         1+: A bit mask indicating invalid world coordinate
d1386 5
d1414 1
a1414 1
  WCSERR_NON_SEPARABLE   = 13	/* Non-separable subimage coordinate
d1570 3
@


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


4.22.1.2
log
@New function wcscompare() contributed by Michael Droettboom.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.22.1.1 2014/04/12 15:06:32 mcalabre Exp mcalabre $
a314 37
* wcscompare() - Compare two wcsprm structs for equality
* ------------------------------------------------------
* wcscompare() compares two wcsprm structs for equality.
*
* Given:
*   cmp       int       A bit field controlling the strictness of the
*                       comparison.  When 0, all fields must be identical.
*
*                       The following constants may be or'ed together to
*                       relax the comparison:
*                         WCSCOMPARE_ANCILLARY: Ignore ancillary keywords
*                           that don't change the WCS transformation, such
*                           as DATE-OBS or EQUINOX.
*                         WCSCOMPARE_TILING: Ignore integral differences in
*                           CRPIXja.  This is the 'tiling' condition, where
*                           two WCSes cover different regions of the same
*                           map projection and align on the same map grid.
*                         WCSCOMPARE_CRPIX: Ignore any differences at all in
*                           CRPIXja.  The two WCSes cover different regions
*                           of the same map projection but may not align on
*                           the same grid map.  Overrides WCSCOMPARE_TILING.
*
*   wcs1      const struct wcsprm*
*                       The first wcsprm struct to compare.
*
*   wcs2      const struct wcsprm*
*                       The second wcsprm struct to compare.
*
* Returned:
*   equal     int*      Non-zero when the given structs are equal.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null pointer passed.
*
*
d489 1
a489 1
*                        1+: A bit mask indicating invalid pixel coordinate
d555 1
a555 1
*                        1+: A bit mask indicating invalid world coordinate
a1348 5
#define WCSCOMPARE_ANCILLARY 0x0001
#define WCSCOMPARE_TILING    0x0002
#define WCSCOMPARE_CRPIX     0x0004


d1372 1
a1372 1
  WCSERR_NON_SEPARABLE   = 13 	/* Non-separable subimage coordinate
a1527 3

int wcscompare(int cmp, const struct wcsprm *wcs1, const struct wcsprm *wcs2,
               int *equal);
@


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: wcs.h,v 4.20.1.3 2014/03/22 05:03:00 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: wcs.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: wcs.h,v 4.19.1.2 2013/12/10 23:06:18 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.20 - C routines that implement the FITS World Coordinate System
d376 5
a380 5
* wcsbchk() - Enable/disable strict bounds checking
* -------------------------------------------------
* wcsbchk() is used to control strict bounds checking in the projection
* routines.  Note that wcsset() always enables strict bounds checking.
* wcsbchk() will invoke wcsset() on the wcsprm struct beforehand if necessary.
d387 11
a397 7
*   bounds    int       If bounds&1 then enable bounds checking for the
*                       sky-to-pixel (s2x) transformation for the AZP, SZP,
*                       TAN, SIN, ZPN, and COP projections.
*
*                       If bounds&2 then enable bounds checking for the
*                       pixel-to-sky transformation for the HPX and XPH
*                       projections.
@


4.20.1.1
log
@WCSLIB 4.20 development branch.
@
text
@d25 1
a25 1
  $Id: wcs.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: wcs.h,v 4.20.1.1 2013/12/18 05:46:55 mcalabre Exp mcalabre $
@


4.20.1.3
log
@In the prologue entry for wcsbchk(), document the new bounds checking
implemented by prjbchk().
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.20.1.2 2014/03/21 06:32:19 mcalabre Exp mcalabre $
d376 5
a380 5
* wcsbchk() - Enable/disable bounds checking
* ------------------------------------------
* wcsbchk() is used to control bounds checking in the projection routines.
* Note that wcsset() always enables bounds checking.  wcsbchk() will invoke
* wcsset() on the wcsprm struct beforehand if necessary.
d387 7
a393 11
*   bounds    int       If bounds&1 then enable strict bounds checking for the
*                       spherical-to-Cartesian (s2x) transformation for the
*                       AZP, SZP, TAN, SIN, ZPN, and COP projections.
*
*                       If bounds&2 then enable strict bounds checking for the
*                       Cartesian-to-spherical (x2s) transformation for the
*                       HPX and XPH projections.
*
*                       If bounds&4 then enable bounds checking on the native
*                       coordinates returned by the Cartesian-to-spherical
*                       (x2s) transformations using prjchk().
@


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: wcs.h,v 4.18.1.3 2013/09/29 10:17:56 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.19 - C routines that implement the FITS World Coordinate System
d376 27
d437 5
d1530 2
@


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


4.19.1.2
log
@Added function wcsbchk() to control strict bounds checking in the
projection routines.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.19.1.1 2013/09/29 14:20:38 mcalabre Exp mcalabre $
a375 27
* wcsbchk() - Enable/disable strict bounds checking
* -------------------------------------------------
* wcsbchk() is used to control strict bounds checking in the projection
* routines.  Note that wcsset() always enables strict bounds checking.
* wcsbchk() will invoke wcsset() on the wcsprm struct beforehand if necessary.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Given:
*   bounds    int       If bounds&1 then enable bounds checking for the
*                       sky-to-pixel (s2x) transformation for the AZP, SZP,
*                       TAN, SIN, ZPN, and COP projections.
*
*                       If bounds&2 then enable bounds checking for the
*                       pixel-to-sky transformation for the HPX and XPH
*                       projections.
*
*                       Zero it to disable all checking.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
a409 5
* Notes:
*   wcsset() always enables strict bounds checking in the projection routines
*   (via a call to prjini()).  Use wcsbchk() to modify bounds-checking after
*   wcsset() is invoked.
*
a1497 2

int wcsbchk(struct wcsprm *wcs, int bounds);
@


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: wcs.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
d207 1
a207 1
* values can be changed in before invoking wcsset().
d228 2
a229 1
*                       the defaults set by wcsini().
d232 2
a233 2
*                       nsub, to indicate the number of axes in the input
*                       image; the number of axes will be returned if
d238 2
a239 2
*                       Set both nsub and axes to zero to do a deep copy of
*                       one wcsprm struct to another.
d253 1
a253 1
*                       On return, *nsub will contain the number of axes in
d849 1
a849 1
*     (Given) ... the rest wavelength in vacuuo [m], only one of which need be
@


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


4.18.1.2
log
@Spelling correction in prologue, vacuuo -> vacuo.
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.18.1.1 2013/07/13 10:02:37 mcalabre Exp mcalabre $
d848 1
a848 1
*     (Given) ... the rest wavelength in vacuo [m], only one of which need be
@


4.18.1.3
log
@Clarified a few points in the prologue comments for wcssub().
@
text
@d25 1
a25 1
  $Id: wcs.h,v 4.18.1.2 2013/07/15 14:17:06 mcalabre Exp mcalabre $
d207 1
a207 1
* values can be changed afterwards, before invoking wcsset().
d228 1
a228 2
*                       the defaults set by wcsini().  They can be changed
*                       later.
d231 2
a232 2
*                       *nsub, which is interpreted to mean all axes in the
*                       input image; the number of axes will be returned if
d237 2
a238 2
*                       Set both nsub (or *nsub) and axes to zero to do a deep
*                       copy of one wcsprm struct to another.
d252 1
a252 1
*                       On return, *nsub will be set to the number of axes in
@


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: wcs.h,v 4.16.1.2 2013/01/29 05:09:44 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: wcs.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: wcs.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
@


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


4.16.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2013, Mark Calabretta
d25 1
a25 1
  $Id: wcs.h,v 4.16.1.1 2012/11/07 04:45:56 cal103 Exp cal103 $
@


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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.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: wcs.h,v 4.9.1.2 2012/01/31 23:56:50 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: wcs.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: wcs.h,v 4.8.1.3 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
d210 5
d233 3
d239 1
a239 1
*                       nsub != 0.  axes itself (the pointer) may be set to
d262 5
a266 4
*                       that were extracted.  The vector length must be
*                       sufficient to contain all axis numbers.  No checks are
*                       performed to verify that the coordinate axes are
*                       consistent, this is done by wcsset().
d316 2
a317 1
*   number of axes in the input image.
d1521 1
a1521 1
#define wcscopy(alloc, wcssrc, wcsdst) wcssub(alloc, wcssrc, 0, 0, wcsdst)
@


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


4.9.1.2
log
@Gave wcssub() the ability to add new axes to a wcsprm.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.9.1.1 2012/01/24 05:41:45 cal103 Exp cal103 $
a209 5
* wcssub() can also add axes to a wcsprm struct.  The new axes will be created
* using the defaults set by wcsini() which produce a simple, unnamed, linear
* axis with world coordinate equal to the pixel coordinate.  These default
* values can be changed in before invoking wcsset().
*
a227 3
*                       Use an axis number of 0 to create a new axis using
*                       the defaults set by wcsini().
*
d231 1
a231 1
*                       nsub != 0x0.  axes itself (the pointer) may be set to
d254 4
a257 5
*                       that were extracted, or 0 for newly created axes.  The
*                       vector length must be sufficient to contain all axis
*                       numbers.  No checks are performed to verify that the
*                       coordinate axes are consistent, this is done by
*                       wcsset().
d307 1
a307 2
*   number of axes in the input image (plus the number of newly-created axes
*   if any were specified on input).
d1511 1
a1511 1
#define wcscopy(alloc, wcssrc, wcsdst) wcssub(alloc, wcssrc, 0x0, 0x0, wcsdst)
@


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: wcs.h,v 4.7.1.5 2011/08/15 06:01:51 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.8 - C routines that implement the FITS World Coordinate System
d1220 2
a1221 1
*     (Given) Axis number (1-relative), as in the FITS PVi_ma keyword.
@


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


4.8.1.2
log
@In the description of the pvcard struct, mention that wcsset() replaces
pvcard::i == 0 with the latitude axis number.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.8.1.1 2011/08/15 08:07:06 cal103 Exp cal103 $
d1220 1
a1220 2
*     (Given) Axis number (1-relative), as in the FITS PVi_ma keyword.  If
*     i == 0, wcsset() will replace it with the latitude axis number.
@


4.8.1.3
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2012, Mark Calabretta
d31 1
a31 1
  $Id: wcs.h,v 4.8.1.2 2011/11/17 03:26:50 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: wcs.h,v 4.6.1.3 2011/01/25 06:35:25 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.7 - C routines that implement the FITS World Coordinate System
d68 3
d158 3
d273 3
d338 2
a339 1
* wcsprt() prints the contents of a wcsprm struct.
d351 20
d402 3
d421 1
d466 3
d485 1
d532 3
d550 1
d616 3
d655 1
d659 1
d682 3
d1078 24
d1136 2
a1137 23
*   char lngtyp[8]
*     (Returned) Four-character WCS celestial longitude and ...
*   char lattyp[8]
*     (Returned) ... latitude axis types. e.g. "RA", "DEC", "GLON", "GLAT",
*     etc. extracted from 'RA--', 'DEC-', 'GLON', 'GLAT', etc. in the first
*     four characters of CTYPEia but with trailing dashes removed.  (Declared
*     as char[8] for alignment reasons.)
*
*   int lng
*     (Returned) Index for the longitude coordinate, and ...
*   int lat
*     (Returned) ... index for the latitude coordinate, and ...
*   int spec
*     (Returned) ... index for the spectral coordinate in the imgcrd[][] and
*     world[][] arrays in the API of wcsp2s(), wcss2p() and wcsmix().
*
*     These may also serve as indices into the pixcrd[][] array provided that
*     the PCi_ja matrix does not transpose axes.
*
*   int cubeface
*     (Returned) Index into the pixcrd[][] array for the CUBEFACE axis.  This
*     is used for quadcube projections where the cube faces are stored on a
*     separate axis (see wcs.h).
d1151 6
d1293 1
d1309 26
d1349 3
a1351 1
				/* For extracting wcstab arrays.            */
a1439 1
  int    *padding;		/* (Dummy inserted for alignment purposes.) */
a1442 1
  int    *types;		/* Coordinate type codes for each axis.     */
d1447 2
d1454 8
a1461 1
  int    m_flag, m_naxis;	/* The remainder are for memory management. */
d1491 2
@


4.7.1.1
log
@WCSLIB 4.7 development branch.
@
text
@d31 1
a31 1
  $Id: wcs.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
@a154 3
* If the return value >= 2, a detailed error message is set in the
* wcs->err struct.  See wcserr.h for error handling instructions.
*                         
a266 3
* If the return value >= 2, a detailed error message is set in the
* wcsdst->err struct.  See wcserr.h for error handling instructions.
*                        
a371 3
* If the return value >= 2, a detailed error message is set in the
* wcs->err struct.  See wcserr.h for error handling instructions.
*                            
a431 3
* If the return value >= 2, a detailed error message is set in the
* wcs->err struct.  See wcserr.h for error handling instructions.
*                            
a493 3
* If the return value >= 2, a detailed error message is set in the
* wcs->err struct.  See wcserr.h for error handling instructions.
*                            
a573 3
* If the return value >= 2, a detailed error message is set in the
* wcs->err struct.  See wcserr.h for error handling instructions.
*                        
a634 3
* If the return value >= 2, a detailed error message is set in the
* wcs->err struct.  See wcserr.h for error handling instructions.
*                            
a1097 4
*   struct wcserr err
*     (Returned) When an error status is returned, this
*     structure contains detailed information about the error.
*     
a1233 1
#include "wcserr.h"
a1248 18
enum wcs_errmsg_enum {
  WCSERR_SUCCESS         = 0, /* Success */
  WCSERR_NULL_POINTER    = 1, /* Null wcsprm pointer passed */
  WCSERR_MEMORY          = 2, /* Memory allocation failed */
  WCSERR_SINGULAR_MTX    = 3, /* Linear transformation matrix is singular */
  WCSERR_BAD_CTYPE       = 4, /* Inconsistent or unrecognized coordinate axis types */
  WCSERR_BAD_PARAM       = 5, /* Invalid parameter value */
  WCSERR_BAD_COORD_TRANS = 6, /* Invalid coordinate transformation parameters */
  WCSERR_ILL_COORD_TRANS = 7, /* Ill-conditioned coordinate transformation parameters */
  WCSERR_BAD_PIX         = 8, /* One or more of the pixel coordinates were invalid */
  WCSERR_BAD_WORLD       = 9, /* One or more of the world coordinates were invalid */
  WCSERR_BAD_WORLD_COORD = 10, /* Invalid world coordinate */
  WCSERR_NO_SOLUTION     = 11, /* No solution found in the specified interval */
  WCSERR_BAD_SUBIMAGE    = 12, /* Invalid subimage specification */
  WCSERR_NON_SEPARABLE   = 13  /* Non-separable subimage coordinate system */
};

  
a1365 6
  /* Error handling                                                         */
  /*------------------------------------------------------------------------*/
  struct wcserr err;

  /* Private                                                                */
  /*------------------------------------------------------------------------*/
@


4.7.1.3
log
@Revised implementation of Michael Droettboom's error messaging system.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.7.1.1 2011/02/07 07:04:22 cal103 Exp cal103 $
a67 3
* wcsperr() prints the error message(s) (if any) stored in a wcsprm struct,
* and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
*
d155 3
a157 3
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
*
d270 3
a272 3
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
*
d335 1
a335 2
* wcsprt() prints the contents of a wcsprm struct using wcsprintf().  Mainly
* intended for diagnostic purposes.
a346 20
* wcsperr() - Print error messages from a wcsprm struct
* -----------------------------------------------------
* wcsperr() prints the error message(s), if any, stored in a wcsprm struct,
* and the linprm, celprm, prjprm, spcprm, and tabprm structs that it contains.
* If there are no errors then nothing is printed.  It uses wcserr_prt(), q.v.
*
* Given:
*   wcs       const struct wcsprm*
*                       Coordinate transformation parameters.
*
*   prefix    const char *
*                       If non-NULL, each output line will be prefixed with
*                       this string.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
d378 3
a380 3
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
*
a396 1
*
d441 3
a443 3
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
*
a459 1
*
d506 3
a508 3
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
*
a523 1
*
d589 3
a591 3
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
*
a627 1
*
a630 1
*
d653 3
a655 3
*                       For returns > 1, a detailed error message is set in
*                       wcsprm::err.
*
a1048 3
*   int padding
*     (An unused variable inserted for alignment purposes only.)
*
d1119 4
a1122 4
*   struct wcserr *err
*     (Returned) When an error status is returned, this struct contains
*     detailed information about the error.
*
d1276 14
a1289 22
  WCSERR_SUCCESS         =  0,	/* Success. */
  WCSERR_NULL_POINTER    =  1,	/* Null wcsprm pointer passed. */
  WCSERR_MEMORY          =  2,	/* Memory allocation failed. */
  WCSERR_SINGULAR_MTX    =  3,	/* Linear transformation matrix is
				   singular. */
  WCSERR_BAD_CTYPE       =  4,	/* Inconsistent or unrecognized coordinate
				   axis types. */
  WCSERR_BAD_PARAM       =  5,	/* Invalid parameter value. */
  WCSERR_BAD_COORD_TRANS =  6,	/* Invalid coordinate transformation
				   parameters. */
  WCSERR_ILL_COORD_TRANS =  7,	/* Ill-conditioned coordinate transformation
				   parameters. */
  WCSERR_BAD_PIX         =  8,	/* One or more of the pixel coordinates were
				   invalid. */
  WCSERR_BAD_WORLD       =  9,	/* One or more of the world coordinates were
				   invalid. */
  WCSERR_BAD_WORLD_COORD = 10,	/* Invalid world coordinate. */
  WCSERR_NO_SOLUTION     = 11,	/* No solution found in the specified
				   interval. */
  WCSERR_BAD_SUBIMAGE    = 12,	/* Invalid subimage specification. */
  WCSERR_NON_SEPARABLE   = 13	/* Non-separable subimage coordinate
				   system. */
d1292 1
a1292 1

d1307 1
a1307 3
				/* For extracting wcstab arrays.  Matches   */
				/* the wtbarr typedef defined in CFITSIO    */
				/* header fitsio.h.                         */
d1396 1
d1412 1
a1412 1
  struct wcserr *err;
d1414 1
a1414 1
  /* Private - the remainder are for memory management.                     */
d1416 1
a1416 1
  int    m_flag, m_naxis;
a1445 2
int wcsperr(const struct wcsprm *wcs, const char *prefix);

@


4.7.1.4
log
@Clarify that detailed error messages are only returned in wcserr if enabled.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.7.1.3 2011/08/09 02:43:50 cal103 Exp cal103 $
d159 1
a159 1
*                       wcsprm::err if enabled, see wcserr_enable().
d274 1
a274 1
*                       wcsprm::err if enabled, see wcserr_enable().
d403 1
a403 1
*                       wcsprm::err if enabled, see wcserr_enable().
d467 1
a467 1
*                       wcsprm::err if enabled, see wcserr_enable().
d533 1
a533 1
*                       wcsprm::err if enabled, see wcserr_enable().
d617 1
a617 1
*                       wcsprm::err if enabled, see wcserr_enable().
d683 1
a683 1
*                       wcsprm::err if enabled, see wcserr_enable().
d1152 2
a1153 2
*     (Returned) If enabled, when an error status is returned this struct
*     contains detailed information about the error, see wcserr_enable().
@


4.7.1.5
log
@Added padding to the wcsprm struct to cater for the Fortran wrappers in
SunOS 5.9.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.7.1.4 2011/08/10 06:52:12 cal103 Exp cal103 $
d1078 2
a1079 23
*   char lngtyp[8]
*     (Returned) Four-character WCS celestial longitude and ...
*   char lattyp[8]
*     (Returned) ... latitude axis types. e.g. "RA", "DEC", "GLON", "GLAT",
*     etc. extracted from 'RA--', 'DEC-', 'GLON', 'GLAT', etc. in the first
*     four characters of CTYPEia but with trailing dashes removed.  (Declared
*     as char[8] for alignment reasons.)
*
*   int lng
*     (Returned) Index for the longitude coordinate, and ...
*   int lat
*     (Returned) ... index for the latitude coordinate, and ...
*   int spec
*     (Returned) ... index for the spectral coordinate in the imgcrd[][] and
*     world[][] arrays in the API of wcsp2s(), wcss2p() and wcsmix().
*
*     These may also serve as indices into the pixcrd[][] array provided that
*     the PCi_ja matrix does not transpose axes.
*
*   int cubeface
*     (Returned) Index into the pixcrd[][] array for the CUBEFACE axis.  This
*     is used for quadcube projections where the cube faces are stored on a
*     separate axis (see wcs.h).
d1115 23
a1137 2
*   void *padding
*     (An unused variable inserted for alignment purposes only.)
a1154 2
*   void *m_padding
*     (For internal use only.)
d1441 1
a1445 2
  int    *types;		/* Coordinate type codes for each axis.     */
  void   *padding;		/* (Dummy inserted for alignment purposes.) */
a1456 1
  void   *m_padding;
@


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: wcs.h,v 4.5.1.2 2010/11/02 06:48:43 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.6 - C routines that implement the FITS World Coordinate System
d1352 1
@


4.6.1.1
log
@WCSLIB 4.6 development branch.
@
text
@d31 1
a31 1
  $Id: wcs.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: wcs.h,v 4.6.1.1 2010/11/16 06:16:19 cal103 Exp cal103 $
@


4.6.1.3
log
@Inserted padding in wcsprm as alerted by gcc 4.5.1 in SunOS 5.9.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.6.1.2 2011/01/14 06:33:16 cal103 Exp cal103 $
a1351 1
  int    *padding;		/* (Dummy inserted for alignment purposes.) */
@


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: wcs.h,v 4.4.1.5 2010/07/07 13:30:37 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.5 - C routines that implement the FITS World Coordinate System
d347 3
a349 4
* projection and it also recognizes GLS as a synonym for SFL.  It also
* translates the AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.), possibly
* changing the input header keywords wcsprm::ctype and/or wcsprm::specsys if
* necessary.
d817 2
a818 2
*     (phi_0,theta_0), the native longitude and latitude of the reference
*     point given by LONPOLEa and LATPOLEa.
@


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


4.5.1.2
log
@Corrected a comment in the prologue.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.5.1.1 2010/07/16 07:05:31 cal103 Exp cal103 $
d347 4
a350 3
* projection and likewise translates GLS into SFL.  It also translates the
* AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.), possibly changing the
* input header keywords wcsprm::ctype and/or wcsprm::specsys if necessary.
d818 2
a819 2
*     phi_0 and theta_0 (the native longitude and latitude of the reference
*     point), LONPOLEa and LATPOLEa respectively.
@


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: wcs.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
d261 5
a265 5
*                          0: Success.
*                          1: Null wcsprm pointer passed.
*                          2: Memory allocation failed.
*                         12: Invalid subimage specification.
*                         13: Non-separable subimage coordinate system.
d347 4
a350 3
* projection and it also recognizes GLS as a synonym for SFL.  It does alias
* translation for the AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.) but
* without changing the input header keywords.
d415 2
a416 1
*                         1: Invalid pixel coordinate.
d477 2
a478 1
*                         1: Invalid world coordinate.
d562 12
a573 12
*                          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.
*                         10: Invalid world coordinate.
*                         11: No solution found in the specified interval.
d614 1
a614 1
*   ctype     char[9]   Required spectral CTYPEia.  Wildcarding may be used as
d623 12
a634 12
*                          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.
*                         12: Invalid subimage specification (no spectral
*                             axis).
d904 2
a905 2
*   int padding
*     (An unused variable inserted for alignment purposes only.)
d1322 1
a1322 1
  int    padding;		/* (Dummy inserted for alignment purposes.) */
d1400 1
a1400 1
	   int stat[]);
d1404 1
a1404 1
	   int stat[]);
d1408 1
a1408 1
	   double theta[], double imgcrd[], double pixcrd[]);
@


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


4.4.1.2
log
@Amended prologue comment re the status return from wcsp2s() and wcss2p().
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.4.1.1 2009/08/10 08:52:49 cal103 Exp cal103 $
d414 1
a414 2
*                         1+: A bit mask indicating invalid pixel coordinate
*                            element(s).
d475 1
a475 2
*                         1+: A bit mask indicating invalid world coordinate
*                            element(s).
@


4.4.1.3
log
@Trivial repair to the indentation.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.4.1.2 2009/08/13 04:20:33 cal103 Exp cal103 $
d1399 1
a1399 1
           int stat[]);
d1403 1
a1403 1
           int stat[]);
d1407 1
a1407 1
           double theta[], double imgcrd[], double pixcrd[]);
@


4.4.1.4
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2010, Mark Calabretta
d31 1
a31 1
  $Id: wcs.h,v 4.4.1.3 2009/09/03 05:02:16 cal103 Exp cal103 $
@


4.4.1.5
log
@Added velref to the wcsprm struct.  Minor tweaks to indentation for status
return values following relaxation of requirements by doxextr.l.
@
text
@d31 1
a31 1
  $Id: wcs.h,v 4.4.1.4 2010/01/19 03:42:50 cal103 Exp cal103 $
d261 5
a265 5
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                        12: Invalid subimage specification.
*                        13: Non-separable subimage coordinate system.
d347 3
a349 4
* projection and it also recognizes GLS as a synonym for SFL.  It also
* translates the AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.), possibly
* changing the input header keywords wcsprm::ctype and/or wcsprm::specsys if
* necessary.
d561 12
a572 12
*                         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.
*                        10: Invalid world coordinate.
*                        11: No solution found in the specified interval.
d613 1
a613 1
*   ctype     char[9]   Desired spectral CTYPEia.  Wildcarding may be used as
d622 12
a633 12
*                         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.
*                        12: Invalid subimage specification (no spectral
*                            axis).
d903 2
a904 2
*   int velref
*     (Given) AIPS velocity code VELREF, refer to spcaips().
d1321 1
a1321 1
  int    velref;		/* AIPS velocity code, VELREF.              */
@


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: wcs.h,v 4.2.1.10 2007/12/22 07:28:38 cal103 Exp $
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 67
a109 768
*      "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.
*
*
*   Summary of the wcs* routines
*   ----------------------------
*   These routines implement the FITS World Coordinate System (WCS) standard
*   which defines methods to be used for computing world coordinates from
*   image pixel coordinates, and vice versa.  They are based on the wcsprm
*   struct, described in detail below, which contains all information needed
*   for the computations.  The struct contains some members that must be set
*   by the caller, and others that are maintained by these routines, somewhat
*   like a C++ class but with no encapsulation.
*
*   Three routines, wcsini(), wcssub(), and wcsfree() are provided to manage
*   the wcsprm struct and another, wcsprt(), to prints its contents.  See
*   "Coordinate transformation parameters" below for an explanation of the
*   anticipated usage of these routines.
*
*   A setup routine, wcsset(), computes intermediate values in the wcsprm
*   struct from parameters in it that were supplied by the caller.  The
*   struct always needs to be set up by wcsset() but this need not be called
*   explicitly - see the explanation of wcs.flag below.
*
*   wcsp2s() and wcss2p() implement the WCS world coordinate transformations.
*   In fact, they are high level driver routines for the WCS linear,
*   logarithmic, celestial, spectral and tabular transformation routines
*   described in lin.h, log.h, cel.h, spc.h and tab.h.
*
*   Given either the celestial longitude or latitude plus an element of the
*   pixel coordinate a hybrid routine, wcsmix(), iteratively solves for the
*   unknown elements.
*
*   wcssptr() translates the spectral axis in a wcsprm struct.  For example, a
*   'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
*
*
*   Default constructor for the wcsprm struct; wcsini()
*   ---------------------------------------------------
*   wcsini() optionally allocates memory for arrays in a wcsprm struct and
*   sets all members of the struct to default values.  Memory is allocated for
*   up to NPVMAX PVi_ma keywords or NPSMAX PSi_ma keywords per WCS
*   representation.  These may be changed via wcsnpv() and wcsnps() before
*   wcsini() is called.
*
*   N.B. every wcsprm struct should be initialized by wcsini(), possibly
*   repeatedly.  On the first invokation, and only the first invokation, the
*   flag member of the wcsprm struct must be set to -1 to initialize memory
*   management, regardless of whether wcsini() will actually be used to
*   allocate memory.
*
*   Given:
*      alloc    int      If true, allocate memory unconditionally for the
*                        crpix, etc. arrays (see "Memory allocation and
*                        deallocation below").
*
*                        If false, it is assumed that pointers to these arrays
*                        have been set by the caller except if they are null
*                        pointers in which case memory will be allocated for
*                        them regardless.  (In other words, setting alloc true
*                        saves having to initalize these pointers to zero.)
*
*      naxis    int      The number of world coordinate axes.  This is used to
*                        determine the length of the various wcsprm vectors
*                        and matrices and therefore the amount of memory to
*                        allocate for them.
*
*   Given and returned:
*      wcs      struct wcsprm*
*                        Coordinate transformation parameters (see below).
*                        Note that, in order to initialize memory management
*                        wcs->flag should be set to -1 when wcs is initialized
*                        for the first time (memory leaks may result if it had
*                        already been initialized).
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*                           2: Memory allocation failed.
*
*
*   Memory allocation for PVi_ma and PSi_ma; wcsnpv() and wcsnps()
*   --------------------------------------------------------------
*   wcsnpv() and wcsnps() change the values of NPVMAX (default 64) and NPSMAX
*   (default 8).  These global variables control the number of PVi_ma and
*   PSi_ma keywords that wcsini() should allocate space for.
*
*   Given:
*      n        int      Value of NPVMAX or NPSMAX; ignored if < 0.
*
*   Function return value:
*               int      Current value of NPVMAX or NPSMAX.
*
*
*   Subimage extraction routine for the wcsprm struct; wcssub()
*   -----------------------------------------------------------
*   wcssub() extracts the coordinate description for a subimage from a wcsprm
*   struct.  It does a deep copy, using wcsini() to allocate memory for its
*   arrays if required.  Only the "information to be provided" part of the
*   struct is extracted; a call to wcsset() is required to set up the
*   remainder.
*
*   The world coordinate system of the subimage must be separable in
*   the sense that the world coordinates at any point in the subimage must
*   depend only on the pixel coordinates of the axes extracted.  In practice,
*   this means that the PCi_ja matrix of the original image must not contain
*   non-zero off-diagonal terms that associate any of the subimage axes with
*   any of the non-subimage axes.
*
*   Note that while the required elements of the tabprm array are extracted,
*   the wtbarr array is not.  (Thus it is not appropriate to call wcssub()
*   after wcstab() but before filling the tabprm structs - refer to wcshdr.h.)
*
*   Given:
*      alloc    int      If true, allocate memory for the crpix, etc. arrays
*                        in the destination (see "Memory allocation and
*                        deallocation below").  Otherwise, it is assumed that
*                        pointers to these arrays have been set by the caller
*                        except if they are null pointers in which case memory
*                        will be allocated for them regardless.
*
*      wcssrc   const struct wcsprm*
*                        Struct to extract from.
*
*   Given and returned:
*      nsub     int*
*      axes     int[]    Vector of length *nsub containing the image axis
*                        numbers (1-relative) to extract.  Order is
*                        significant; axes[0] is the axis number of the input
*                        image that corresponds to the first axis in the
*                        subimage, etc.
*
*                        nsub (the pointer) may be set to zero, and so also
*                        may *nsub, to indicate the number of axes in the
*                        input image; the number of axes will be returned if
*                        nsub != 0.  axes itself (the pointer) may be set to
*                        zero to indicate the first *nsub axes in their
*                        original order.
*
*                        Set both nsub and axes to zero to do a deep copy of
*                        one wcsprm struct to another.
*
*                        Subimage extraction by coordinate axis type may be
*                        done by setting the elements of axes[] to the
*                        following special preprocessor macro values:
*
*                           WCSSUB_LONGITUDE: Celestial longitude.
*                           WCSSUB_LATITUDE:  Celestial latitude.
*                           WCSSUB_CUBEFACE:  Quadcube CUBEFACE axis.
*                           WCSSUB_SPECTRAL:  Spectral axis.
*                           WCSSUB_STOKES:    Stokes axis.
*
*                        See note 2 below for further usage notes.
*
*                        On return, *nsub will contain the number of axes in
*                        the subimage; this may be zero if there were no axes
*                        of the required type(s) (in which case no memory will
*                        be allocated).  axes[] will contain the axis numbers
*                        that were extracted.  The vector length must be
*                        sufficient to contain all axis numbers.  No checks
*                        are performed to verify that the coordinate axes are
*                        consistent, this is done by wcsset().
*
*      wcsdst   struct wcsprm*
*                        Struct describing the subimage.  wcsdst->flag should
*                        be set to -1 if wcsdst was not previously initialized
*                        (memory leaks may result if it was previously
*                        initialized).
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*                           2: Memory allocation failed.
*                          12: Invalid subimage specification.
*                          13: Non-separable subimage coordinate system.
*
*
*   Copy routine for the wcsprm struct; wcscopy()
*   ---------------------------------------------
*   wcscopy() does a deep copy of one wcsprm struct to another.  As of
*   WCSLIB 3.6, it is implemented as a preprocessor macro that invokes
*   wcssub() with the nsub and axes pointers both set to zero.
*
*
*   Destructor for the wcsprm struct; wcsfree()
*   -------------------------------------------
*   wcsfree() frees memory allocated for the wcsprm arrays by wcsini() and/or
*   wcsset().  wcsini() records the memory it allocates and wcsfree() will
*   only attempt to free this.
*
*   N.B. wcsfree() must not be invoked on a wcsprm struct that was not
*   initialized by wcsini().
*
*   Returned:
*      wcs      struct wcsprm*
*                        Coordinate transformation parameters (see below).
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
*
*   Print routine for the wcsprm struct; wcsprt()
*   ---------------------------------------------
*   wcsprt() prints the contents of a wcsprm struct.
*
*   Given:
*      wcs      const struct wcsprm*
*                        Coordinate transformation parameters (see below).
*
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Null wcsprm pointer passed.
*
*
*   Setup routine; wcsset()
*   -----------------------
*   wcsset() sets up a wcsprm struct according to information supplied within
*   it (see "Coordinate transformation parameters" below).
*
*   wcsset() recognizes the NCP projection and converts it to the equivalent
*   SIN projection and it also recognizes GLS as a synonym for SFL.  It does
*   alias translation for the AIPS spectral types ('FREQ-LSR', 'FELO-HEL',
*   etc.) but without changing the input header keywords.
*
*   Note that this routine need not be called directly; it will be invoked by
*   wcsp2s() and wcss2p() if the "flag" struct member is anything other than a
*   predefined magic value.
*
*   Given and returned:
*      wcs      struct wcsprm*
*                        Coordinate transformation parameters (see below).
*
*   Function return value:
*               int      Status return value:
*                           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.
*
*
*   Pixel-to-world transformation; wcsp2s()
*   ---------------------------------------
*   wcsp2s() transforms pixel coordinates to world coordinates.
*
*   Given or returned:
*      wcs      struct wcsprm*
*                        Coordinate transformation parameters (see below).
*
*   Given:
*      ncoord   int      The number of coordinates, each of vector length
*      nelem    int      nelem but containing wcs.naxis coordinate elements.
*                        Thus nelem must equal or exceed the value of the
*                        NAXIS keyword unless ncoord == 1, in which case nelem
*                        is not used.
*      pixcrd   const double[ncoord][nelem]
*                        Array of pixel coordinates.
*
*   Returned:
*      imgcrd   double[ncoord][nelem]
*                        Array of intermediate world coordinates.  For
*                        celestial axes, imgcrd[][wcs.lng] and
*                        imgcrd[][wcs.lat] are the projected x-, and
*                        y-coordinates, in "degrees".  For spectral axes,
*                        imgcrd[][wcs.spec] is the intermediate spectral
*                        coordinate, in SI units.
*
*      phi,     double[ncoord]
*      theta             Longitude and latitude in the native coordinate
*                        system of the projection, in degrees.
*
*      world    double[ncoord][nelem]
*                        Array of world coordinates.  For celestial axes,
*                        world[][wcs.lng] and world[][wcs.lat] are the
*                        celestial longitude and latitude, in degrees.  For
*                        spectral axes, imgcrd[][wcs.spec] is the intermediate
*                        spectral coordinate, in SI units.
*
*      stat     int[ncoord]
*                        Status return value for each coordinate:
*                           0: Success.
*                           1: Invalid pixel coordinate.
*
*   Function return value:
*               int      Status return value:
*                           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.
*                           8: One or more of the pixel coordinates were
*                              invalid, as indicated by the stat vector.
*
*
*   World-to-pixel transformation; wcss2p()
*   ---------------------------------------
*   wcss2p() transforms world coordinates to pixel coordinates.
*
*   Given or returned:
*      wcs      struct wcsprm*
*                        Coordinate transformation parameters (see below).
*
*   Given:
*      ncoord   int      The number of coordinates, each of vector length
*      nelem    int      nelem but containing wcs.naxis coordinate elements.
*                        Thus nelem must equal or exceed the value of the
*                        NAXIS keyword unless ncoord == 1, in which case nelem
*                        is not used.
*      world    const double[ncoord][nelem]
*                        Array of world coordinates.  For celestial axes,
*                        world[][wcs.lng] and world[][wcs.lat] are the
*                        celestial longitude and latitude, in degrees. For
*                        spectral axes, world[][wcs.spec] is the spectral
*                        coordinate, in SI units.
*
*   Returned:
*      phi,     double[ncoord]
*      theta             Longitude and latitude in the native coordinate
*                        system of the projection, in degrees.
*
*      imgcrd   double[ncoord][nelem]
*                        Array of intermediate world coordinates.  For
*                        celestial axes, imgcrd[][wcs.lng] and
*                        imgcrd[][wcs.lat] are the projected x-, and
*                        y-coordinates, in "degrees".  For quadcube
*                        projections with a CUBEFACE axis the face number is
*                        also returned in imgcrd[][wcs.cubeface].  For
*                        spectral axes, imgcrd[][wcs.spec] is the intermediate
*                        spectral coordinate, in SI units.
*
*      pixcrd   double[ncoord][nelem]
*                        Array of pixel coordinates.
*
*      stat     int[ncoord]
*                        Status return value for each coordinate:
*                           0: Success.
*                           1: Invalid world coordinate.
*
*   Function return value:
*               int      Status return value:
*                           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.
*                           9: One or more of the world coordinates were
*                              invalid, as indicated by the stat vector.
*
*
*   Hybrid transformation; wcsmix()
*   -------------------------------
*   wcsmix(), given either the celestial longitude or latitude plus an element
*   of the pixel coordinate, solves for the remaining elements by iterating on
*   the unknown celestial coordinate element using wcss2p().
*
*   Given or returned:
*      wcs      struct wcsprm*
*                        Indices for the celestial coordinates obtained
*                        by parsing the ctype[] array (see below).
*
*   Given:
*      mixpix   int      Which element of the pixel coordinate is given.
*      mixcel   int      Which element of the celestial coordinate is given:
*                           1: Celestial longitude is given in
*                              world[wcs.lng], latitude returned in
*                              world[wcs.lat].
*                           2: Celestial latitude is given in
*                              world[wcs.lat], longitude returned in
*                              world[wcs.lng].
*
*      vspan    const double[2]
*                        Solution interval for the celestial coordinate, in
*                        degrees.  The ordering of the two limits is
*                        irrelevant.  Longitude ranges may be specified with
*                        any convenient normalization, for example [-120,+120]
*                        is the same as [240,480], except that the solution
*                        will be returned with the same normalization, i.e.
*                        lie within the interval specified.
*
*      vstep    const double
*                        Step size for solution search, in degrees.  If zero,
*                        a sensible, although perhaps non-optimal default will
*                        be used.
*
*      viter    int      If a solution is not found then the step size will be
*                        halved and the search recommenced.  viter controls
*                        how many times the step size is halved.  The allowed
*                        range is 5 - 10.
*
*   Given and returned:
*      world    double[naxis]
*                        World coordinate elements.  world[wcs.lng] and
*                        world[wcs.lat] are the celestial longitude and
*                        latitude, in degrees.  Which is given and which
*                        returned depends on the value of mixcel.  All other
*                        elements are given.
*
*   Returned:
*      phi,     double[naxis]
*      theta             Longitude and latitude in the native coordinate
*                        system of the projection, in degrees.
*
*      imgcrd   double[naxis]
*                        Image coordinate elements.  imgcrd[wcs.lng] and
*                        imgcrd[wcs.lat] are the projected x-, and
*                        y-coordinates, in "degrees".
*
*   Given and returned:
*      pixcrd   double[naxis]
*                        Pixel coordinate.  The element indicated by mixpix is
*                        given and the remaining elements are returned.
*
*   Function return value:
*               int      Status return value:
*                           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.
*                          10: Invalid world coordinate.
*                          11: No solution found in the specified interval.
*
*
*   Spectral axis translation; wcssptr()
*   ------------------------------------
*   wcssptr() translates the spectral axis in a wcsprm struct.  For example, a
*   'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
*
*   Given or returned:
*      wcs      struct wcsprm*
*                        Coordinate transformation parameters (see below).
*      i        int*     Index of the spectral axis (0-rel).  If given < 0 it
*                        will be set to the first spectral axis identified
*                        from the ctype[] keyvalues in the wcsprm struct.
*      ctype    char[9]  Required spectral CTYPEia.  Wildcarding may be used
*                        as for the ctypeS2 argument to spctrn() as described
*                        in the prologue of spc.h, i.e. if the final three
*                        characters are specified as "???", or if just the
*                        eighth character is specified as '?', the correct
*                        algorithm code will be substituted and returned.
*
*   Function return value:
*               int      Status return value:
*                           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.
*                          12: Invalid subimage specification (no spectral
*                              axis).
*
*
*   Notes
*   -----
*    1) The quadcube projections (TSC, CSC, QSC) may be represented in FITS in
*       either of two ways:
*
*          a) The six faces may be laid out in one plane and numbered as
*             follows:
*
*                                       0
*
*                              4  3  2  1  4  3  2
*
*                                       5
*
*             Faces 2, 3 and 4 may appear on one side or the other (or both).
*             The world-to-pixel routines map faces 2, 3 and 4 to the left but
*             the pixel-to-world routines accept them on either side.
*
*          b) The "COBE" convention in which the six faces are stored in a
*             three-dimensional structure using a "CUBEFACE" axis indexed from
*             0 to 5 as above.
*
*       These routines support both methods; wcsset() determines which is
*       being used by the presence or absence of a CUBEFACE axis in ctype[].
*       wcsp2s() and wcss2p() translate the CUBEFACE axis representation to
*       the single plane representation understood by the lower-level WCSLIB
*       projection routines.
*
*    2) In wcssub(), combinations of subimage axes of particular types may be
*       extracted in the same order as they occur in the input image by
*       combining preprocessor codes, for example
*
*          *nsub = 1;
*          axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
*
*       would extract the longitude, latitude, and spectral axes in the same
*       order as the input image.  If one of each were present, *nsub = 3
*       would be returned.
*
*       For convenience, WCSSUB_CELESTIAL is defined as the combination
*       WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
*
*       The codes may also be negated to extract all but the types specified,
*       for example
*
*          *nsub = 4;
*          axes[0] = WCSSUB_LONGITUDE;
*          axes[1] = WCSSUB_LATITUDE;
*          axes[2] = WCSSUB_CUBEFACE;
*          axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
*
*       The last of these specifies all axis types other than spectral or
*       Stokes.  Extraction is done in the order specified by axes[] a
*       longitude axis (if present) would be extracted first (via axes[0]) and
*       not subsequently (via axes[3]).  Likewise for the latitude and
*       cubeface axes in this example.
*
*       From the foregoing, it is apparent that the value of *nsub returned
*       may be less than or greater than that given.  However, it will never
*       exceed the number of axes in the input image.
*
*
*   Coordinate transformation parameters
*   ------------------------------------
*   The wcsprm struct consists of a number of data members that must be
*   supplied and others that are computed from them.
*
*   In practice, it is expected that a FITS header parser would scan the FITS
*   header until it encountered the NAXIS (or WCSAXESa) keyword which must
*   occur near the start of the header before any of the WCS keywords.  It
*   would then use wcsini() to allocate memory for arrays in the wcsprm struct
*   and set default values.  Then as it read and identified each WCS header
*   keyword record it would load the value into the relevant wcsprm array
*   element.  This is essentially what wcspih() does - refer to the prologue
*   of wcshdr.h.
*
*   As the final step, wcsset() is invoked, either directly or indirectly, to
*   set the derived members of the wcsprm struct.  wcsset() strips off
*   trailing blanks in all string members and null-fills the character array.
*
*      int flag
*         This flag must be set to zero whenever any of the following members
*         of the wcsprm struct are set or modified.  This signals the setup
*         routine, wcsset(), to recompute intermediaries.
*
*         flag should be set to -1 when wcsini() is called for the first time
*         for a wcsprm struct in order to initialize memory management.  It
*         must ONLY be used on the first initialization otherwise memory leaks
*         may result.
*
*      int naxis
*         Number of pixel and world coordinate elements, given by the NAXIS or
*         WCSAXESa keyvalues.
*
*      double *crpix
*         Address of the first element of an array of double containing the
*         coordinate reference pixel, CRPIXja.
*
*      double *pc
*         Address of the first element of the PCi_ja (pixel coordinate)
*         transformation matrix.  The expected order is
*
*            pc = {PC1_1, PC1_2, PC2_1, PC2_2};
*
*         This may be constructed conveniently from a two-dimensional array
*         via
*
*            double m[2][2] = {{PC1_1, PC1_2},
*                              {PC2_1, PC2_2}};
*
*         which is equivalent to,
*
*            double m[2][2];
*            m[0][0] = PC1_1;
*            m[0][1] = PC1_2;
*            m[1][0] = PC2_1;
*            m[1][1] = PC2_2;
*
*         The storage order in each case is
*
*            PC1_1, PC1_2, PC2_1, PC2_2
*
*         so it would be legitimate to set pc = *m.
*
*      double *cdelt
*         Address of the first element of an array of double containing the
*         coordinate increments, CDELTia.
*
*      double *crval
*         Address of the first element of an array of double containing the
*         coordinate reference values, CRVALia.
*
*      char (*cunit)[72]
*         Address of the first element of an array of char[72] containing the
*         CUNITia keyvalues which define the units of measurement of the
*         CRVALia, CDELTia, and CDi_ja keywords.
*
*         As CUNITia is an optional header keyword, cunit[][72] may be left
*         blank but otherwise is expected to contain a standard units
*         specification as defined by WCS Paper I.  Utility function
*         wcsutrn(), described in wcsunits.h, is available to translate
*         commonly used non-standard units specifications but this must be
*         done as a separate step before invoking wcsset().
*
*         For celestial axes, if cunit[][72] is not blank, wcsset() uses
*         wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to
*         degrees.  It then resets cunit[][72] to "deg".
*
*         For spectral axes, if cunit[][72] is not blank, wcsset() uses
*         wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to SI
*         units.  It then resets cunit[][72] accordingly.
*
*         wcsset() ignores cunit[][72] for other coordinate types; cunit[][72]
*         may be used to label coordinate values.
*
*         These variables accomodate the longest allowed string-valued FITS
*         keyword, being limited to 68 characters, plus the null-terminating
*         character.
*
*      char (*ctype)[72]
*         Address of the first element of an array of char[72] containing the
*         coordinate axis types, CTYPEia.
*
*         The ctype[][72] keyword values must be in upper case and there must
*         be zero or one pair of matched celestial axis types, and zero or one
*         spectral axis.  The ctype[][72] strings should be padded with blanks
*         on the right and null-terminated so that they are at least eight
*         characters in length.
*
*         These variables accomodate the longest allowed string-valued FITS
*         keyword, being limited to 68 characters, plus the null-terminating
*         character.
*
*      double lonpole, latpole
*         The native longitude and latitude of the celestial pole, LONPOLEa
*         and LATPOLEa (deg).  These may be left to default to values set by
*         wcsini() (as described in the prologue of cel.h), but in any case
*         they will be reset by wcsset() to the values actually used.  Note
*         therefore that if the wcsprm struct is reused without resetting
*         them, wether directly or via wcsini(), they will no longer have
*         their default values.
*
*      double restfrq, restwav
*         Rest frequency (Hz) and/or wavelength (m).
*
*      int npv, npvmax
*      struct pvcard *pv
*         Address of the first element of an array of length npvmax of pvcard
*         structs:
*
*            struct pvcard {
*               int i;			...Axis number, as in PVi_ma,
*                                          (i.e. 1-relative).
*               int m;			...Parameter number, as in PVi_ma,
*                                          (i.e. 0-relative).
*               double value;		...Parameter value.
*            };
*
*         As a FITS header parser encounters each PVi_ma keyword it should
*         load it into a pvcard struct in the array and increment npv.
*         wcsset() interprets these as required.
*
*         npvmax will be set by wcsini() if it allocates memory for pv[],
*         otherwise it must be set by the caller.  See also wcsnpv() above.
*
*      int nps, npsmax
*      struct pscard *ps
*         Address of the first element of an array of length npsmax of pscard
*         structs:
*
*            struct pscard {
*               int i;			...Axis number, as in PSi_ma,
*                                          (i.e. 1-relative).
*               int m;			...Parameter number, as in PSi_ma,
*                                          (i.e. 0-relative).
*               char value[72];		...Parameter value.
*            };
*
*         As a FITS header parser encounters each PSi_ma keyword it should
*         load it into a pscard struct in the array and increment nps.
*         wcsset() interprets these as required (currently no PSi_ma keyvalues
*         are recognized).
*
*         npsmax will be set by wcsini() if it allocates memory for ps[],
*         otherwise it must be set by the caller.  See also wcsnps() above.
*
*      int altlin
*      double *cd
*      double *crota
*         For historical compatibility, the wcsprm struct supports two
*         alternate specifications of the linear transformation matrix, those
*         associated with the CDi_ja and CROTAia keywords.  Although these may
*         not formally co-exist with PCi_ja, the approach here is simply to
*         ignore them if given in conjunction with PCi_ja.
*
*         altlin is a bit flag that denotes which of these keywords are
*         present in the header:
*
*         Bit 0: PCi_ja is present.
*
*         Bit 1: CDi_ja is present.  Matrix elements in the IRAF convention
*                are equivalent to the product CDi_ja = CDELTia * PCi_ja, but
*                the defaults differ from that of the PCi_ja matrix.  If one
*                or more CDi_ja keywords are present then all unspecified
*                CDi_ja default to zero.  If no CDi_ja (or CROTAia) keywords
*                are present, then the header is assumed to be in PCi_ja form
*                whether or not any PCi_ja keywords are present since this
*                results in an interpretation of CDELTia consistent with the
*                original FITS specification.
*
*                While CDi_ja may not formally co-exist with PCi_ja, it may
*                co-exist with CDELTia and CROTAia which are to be ignored.
*
*         Bit 2: CROTAia is present.  In the AIPS convention, CROTAia may only
*                be associated with the latitude axis of a celestial axis
*                pair.  It specifies a rotation in the image plane that is
*                applied AFTER the CDELTia; any other CROTAia keywords are
*                ignored.
*
*                CROTAia may not formally co-exist with PCi_ja.  CROTAia and
*                CDELTia may formally co-exist with CDi_ja but if so are to be
*                ignored.
*
*         CDi_ja and CROTAia keywords, if found, are to be stored in the cd
*         and crota arrays which are dimensioned similarly to pc and cdelt.
*         FITS header parsers should use the following precedure:
*            Whenever a PCi_ja  keyword is encountered: altlin |= 1;
*            Whenever a CDi_ja  keyword is encountered: altlin |= 2;
*            Whenever a CROTAia keyword is encountered: altlin |= 4;
*         If none of these bits are set the PCi_ja representation results,
*         i.e. pc and cdelt will be used as given.
*
*         These alternate specifications of the linear transformation matrix
*         are translated immediately to PCi_ja by wcsset() and are nowhere
*         visible to the lower-level routines.  In particular, wcsset() resets
*         cdelt to unity if CDi_ja is present (and no PCi_ja).  If no CROTAia
*         is associated with the latitude axis, wcsset() reverts to a unity
*         PCi_ja matrix.
*
*   The following members of the wcsprm struct are provided solely so that it
*   may contain a complete copy of all WCS keywords associated with a
*   particular coordinate representation.  They are not used by any WCSLIB
a111 261
*      char alt[4]
*         Character code for alternate coordinate descriptions (i.e. the "a"
*         in keyword names such as CTYPEia).  This is blank for the primary
*         coordinate description, or one of the 26 upper-case letters, A-Z.
*
*         An array of four characters is provided for alignment purposes,
*         only the first is used.
*
*      int colnum
*         Where the coordinate representation is associated with an image-
*         array column in a FITS binary table, this variable may be used to
*         record the relevant column number.
*
*         It should be set to zero for an image header or pixel list.
*
*      int *colax
*         Address of the first element of an array of int recording the column
*         numbers for each axis in a pixel list.
*
*         The array elements should be set to zero for an image header or
*         image array in a binary table.
*
*      char (*cname)[72]
*         The address of the first element of an array of char[72] containing
*         the coordinate axis names, CNAMEia.
*
*         These variables accomodate the longest allowed string-valued FITS
*         keyword, being limited to 68 characters, plus the null-terminating
*         character.
*
*      double *crder, *csyer
*         Addresses of the first elements of arrays of double recording the
*         random and systematic error in the coordinate value, CRDERia and
*         CSYERia.
*
*      char dateavg[72], dateobs[72]
*         The date of observation in ISO format, yyyy-mm-ddThh:mm:ss.
*         DATE-AVG refers to a representative mid-point of the observation and
*         DATE-OBS refers to the start of the observation unless otherwise
*         explained in the comment field of the DATE-OBS keyword.
*
*      double equinox
*         The equinox associated with dynamical equatorial or ecliptic
*         coordinate systems, EQUINOXa (or EPOCH in older headers).  Not
*         applicable to ICRS equatorial or ecliptic coordinates.
*
*      double mjdavg, mjdobs
*         Modified Julian Date (MJD = JD - 2400000.5), MJD-AVG and MJD-OBS,
*         corresponding to DATE-AVG and DATE-OBS.
*
*      double obsgeo[3]
*         Location of the observer in a standard terrestrial reference frame,
*         OBSGEO-X, OBSGEO-Y, OBSGEO-Z (in metres).
*
*      char radesys[72]
*         The equatorial or ecliptic coordinate system type, RADESYSa.
*
*      char specsys[72], ssysobs[72]
*      double velosys
*         Spectral reference frame (standard of rest), SPECSYSa, and the
*         actual frame in which there is no differential variation in the
*         spectral coordinate across the field-of-view, SSYSOBSa.  The
*         relative radial velocity (m/s) between the observer and the selected
*         standard of rest in the direction of the celestial reference
*         coordinate, VELOSYSa.
*
*      char ssyssrc[72]
*      double zsource
*         The redshift, ZSOURCEa, of the source and the spectral reference
*         frame (standard of rest) in which this was measured, SSYSSRCa.
*
*      double velangl
*         The angle in degrees that should be used to decompose an observed
*         velocity into radial and transverse components.
*
*      char wcsname[72]
*         The name given to the coordinate representation WCSNAMEa.  This
*         variable accomodates the longest allowed string-valued FITS keyword,
*         being limited to 68 characters, plus the null-terminating character.
*
*
*   The tabprm structs contain some members that must be supplied and others
*   that are derived.  The information to be supplied comes primarily from
*   arrays stored in one or more FITS binary table extensions.  These arrays,
*   referred to here as "wcstab arrays", are themselves located by parameters
*   stored in the FITS image header.
*
*   Function wcstab(), which is invoked automatically by wcspih(), sets up an
*   array of wtbarr structs to assist in extracting this information.  Refer
*   to the usage notes for wcspih() and wcstab() in wcshdr.h, and also the
*   prologue to tab.h.
*
*   For C++ usage, because of a name space conflict with the wtbarr typedef
*   defined in CFITSIO header fitsio.h, the wtbarr struct is renamed to
*   wtbarr_s by preprocessor macro substitution with scope limited to wcs.h
*   itself.
*
*      int ntab
*      struct tabprm *tab
*         Address of the first element of an array of ntab tabprm structs used
*         to store tabular transformation parameters.
*
*      int nwtb
*      struct wtbarr *wtb
*         Address of the first element of an array of nwtb wtbarr structs used
*         in extracting wcstab arrays from a FITS binary table.  The wtbarr
*         structs contain the following members:
*
*         int i
*            Image axis number.
*
*         int m
*            wcstab array axis number for index vectors.
*
*         int kind
*            Character identifying the wcstab array type:
*               'c': coordinate array,
*               'i': index vector.
*
*         char extnam[72]
*            EXTNAME identifying the binary table extension.
*
*         int extver
*            EXTVER identifying the binary table extension.
*
*         int extlev
*            EXTLEV identifying the binary table extension.
*
*         char ttype[72]
*            TTYPEn identifying the column of the binary table that contains
*            the wcstab array.
*
*         long row
*            Table row number.
*
*         int ndim
*            Expected dimensionality of the wcstab array.
*
*         int *dimlen
*            Address of the first element of an array of int of length ndim
*            into which the wcstab array axis lengths are to be written.
*
*         double **arrayp
*            Pointer to an array of double which is to be allocated by the
*            user and into which the wcstab array is to be written.
*
*
*   The remaining members of the wcsprm struct are maintained by wcsset() and
*   must not be modified elsewhere:
*
*      double *types
*         Address of the first element of an array of int containing a four-
*         digit type code for each axis.
*
*            First digit (i.e. 1000s):
*               0: Non-specific coordinate type.
*               1: Stokes coordinate.
*               2: Celestial coordinate (including CUBEFACE).
*               3: Spectral coordinate.
*
*            Second digit (i.e. 100s):
*               0: Linear axis.
*               1: Quantized axis (STOKES, CUBEFACE).
*               2: Non-linear celestial axis.
*               3: Non-linear spectral axis.
*               4: Logarithmic axis.
*               5: Tabular axis.
*
*            Third digit (i.e. 10s):
*               0: Group number, e.g. lookup table number, being an index into
*                  the tabprm array (see below).
*
*         The fourth digit is used as a qualifier depending on the axis type.
*         For celestial axes:
*               0: Longitude coordinate.
*               1: Latitude coordinate.
*               2: CUBEFACE number.
*         For lookup tables: the axis number in a multidimensional table.
*
*         CTYPEia in "4-3" form with unrecognized algorithm code will have its
*         type set to -1 and generate an error.
*
*      char lngtyp[8], lattyp[8]
*         Four-character WCS celestial axis types. e.g. RA, DEC, GLON, GLAT,
*         etc.  (Declared as char[8] for alignment reasons.)
*
*      int lng, lat, spec
*         Indices into the imgcrd[][], and world[][] arrays as described
*         above. These may also serve as indices into the pixcrd[][] array
*         provided that the PCi_ja matrix does not transpose axes.
*
*      int cubeface
*         Index into the pixcrd[][] array for the CUBEFACE axis.  This is used
*         for quadcube projections where the cube faces are stored on a
*         separate axis (see note 1 above).
*
*      struct linprm lin
*         Linear transformation parameters (usage is described in the
*         prologue to lin.h).
*
*      struct celprm cel
*         Celestial transformation parameters (usage is described in the
*         prologue to cel.h).
*
*      struct spcprm spc
*         Spectral transformation parameters (usage is described in the
*         prologue to spc.h).
*
*      The remaining members of the wcsprm struct are used for memory
*      management by wcsini() and wcsfree().
*
*
*   Vector arguments
*   ----------------
*   Arrays of pixel and world coordinates are two dimensional, i.e.
*   pixcrd[ncoord][nelem], where nelem must equal or exceed the number of
*   coordinate elements, naxis (i.e. the value of the NAXIS keyword), stored
*   in the wcsprm struct.  Exception: when ncoord == 1, nelem is not used.
*
*   Note that the function prototypes must declare two-dimensional arrays as
*   one-dimensional to avoid warnings about declaration of "incomplete types".
*   This was considered preferable to declaring them as simple pointers-to-
*   double which gives no indication that storage is associated with them.
*
*
*   Memory allocation and deallocation
*   ----------------------------------
*   wcsini() optionally allocates memory for the crpix, pc, cdelt, crval,
*   cunit, ctype, pv, ps, cd, crota, colax, cname, crder, and csyer arrays in
*   the wcsprm struct as described in the usage notes above.
*
*   Note that wcsini() does not allocate memory for the tab array - refer to
*   the usage notes for wcstab() in wcshdr.h.
*
*   If the pc matrix is not unity, wcsset() also allocates memory for the
*   piximg and imgpix arrays.  The caller must not modify these.
*
*   wcsini() maintains a record of memory it has allocated and this is used
*   by wcsfree().  wcsini() uses wcsfree() to free any memory that it may have
*   allocated on a previous invokation.  Thus it is not necessary for the
*   caller to invoke wcsfree() separately if wcsini() is invoked repeatedly on
*   the same wcsprm struct.  Likewise, wcsset() deallocates memory that it may
*   have allocated in the same wcsprm struct on a previous invokation.
*
*   A memory leak will result if a wcsprm struct goes out of scope before the
*   memory has been free'd, either by wcsfree() or otherwise.  Likewise, if
*   the wcsprm struct itself has been malloc'd and the allocated memory is not
*   free'd when the memory for the struct is free'd.  A leak may also arise if
*   the caller interferes with the array pointers in the "private" part of the
*   wcsprm struct.
*
*   Beware of making a shallow copy of a wcsprm struct by assignment; any
*   changes made to allocated memory in one would be reflected in the other,
*   and if the memory allocated for one was free'd the other would reference
*   unallocated memory.  Use wcssub() instead to make a deep copy.
*
*
*   Status return values
*   --------------------
*   Error messages to match the status value returned from each function are
*   encoded in the wcs_errmsg character array.
d113 458
d572 1
a572 2
*   wcsmix() algorithm
*   ------------------
d581 4
a584 4
*   within the specified solution interval then a search is made for a "non-
*   crossing" solution as may arise from a point of tangency.  The process is
*   complicated by having to make allowance for the discontinuities that occur
*   in all map projections.
d589 4
a592 4
*   Note the circumstance that arises when the solution point lies at a
*   native pole of a projection in which the pole is represented as a finite
*   curve, for example the zenithals and conics.  In such cases two or more
*   valid solutions may exist but WCSMIX only ever returns one.
d599 624
a1245 9
#define wcsini_errmsg wcs_errmsg
#define wcssub_errmsg wcs_errmsg
#define wcscopy_errmsg wcs_errmsg
#define wcsfree_errmsg wcs_errmsg
#define wcsprt_errmsg wcs_errmsg
#define wcsset_errmsg wcs_errmsg
#define wcsp2s_errmsg wcs_errmsg
#define wcss2p_errmsg wcs_errmsg
#define wcsmix_errmsg wcs_errmsg
d1247 1
a1247 1
				/* Struct used for storing PVi_ma keywords. */
d1249 3
a1251 3
   int i;			/* Axis number, as in PVi_ma (1-relative).  */
   int m;			/* Parameter number, ditto  (0-relative).   */
   double value;		/* Parameter value.                         */
d1254 1
a1254 1
				/* Struct used for storing PSi_ma keywords. */
d1256 3
a1258 3
   int i;			/* Axis number, as in PSi_ma (1-relative).  */
   int m;			/* Parameter number, ditto  (0-relative).   */
   char value[72];		/* Parameter value.                         */
d1266 12
a1277 12
   int  i;			/* Image axis number.                       */
   int  m;			/* Array axis number for index vectors.     */
   int  kind;			/* wcstab array type.                       */
   char extnam[72];		/* EXTNAME of binary table extension.       */
   int  extver;			/* EXTVER  of binary table extension.       */
   int  extlev;			/* EXTLEV  of binary table extension.       */
   char ttype[72];		/* TTYPEn of column containing the array.   */
   long row;			/* Table row number.                        */
   int  ndim;			/* Expected wcstab array dimensionality.    */
   int  *dimlen;		/* Where to write the array axis lengths.   */
   double **arrayp;		/* Where to write the address of the array  */
                                /* allocated to store the wcstab array.     */
d1282 34
a1315 32
   /* Initialization flag (see the prologue above).                         */
   /*-----------------------------------------------------------------------*/
   int    flag;			/* Set to zero to force initialization.     */

   /* FITS header keyvalues to be provided (see the prologue above).        */
   /*-----------------------------------------------------------------------*/
   int    naxis;		/* Number of axes (pixel and coordinate).   */
   double *crpix;		/* CRPIXja keyvalues for each pixel axis.   */
   double *pc;			/* PCi_ja  linear transformation matrix.    */
   double *cdelt;		/* CDELTia keyvalues for each coord axis.   */
   double *crval;		/* CRVALia keyvalues for each coord axis.   */

   char   (*cunit)[72];		/* CUNITia keyvalues for each coord axis.   */
   char   (*ctype)[72];		/* CTYPEia keyvalues for each coord axis.   */

   double lonpole;		/* LONPOLEa keyvalue.                       */
   double latpole;		/* LATPOLEa keyvalue.                       */

   double restfrq;		/* RESTFRQa keyvalue.                       */
   double restwav;		/* RESTWAVa keyvalue.                       */

   int    npv;			/* Number of PVi_ma keywords, and the       */
   int    npvmax;		/* number for which space was allocated.    */
   struct pvcard *pv;		/* PVi_ma keywords for each i and m.        */

   int    nps;			/* Number of PSi_ma keywords, and the       */
   int    npsmax;		/* number for which space was allocated.    */
   struct pscard *ps;		/* PSi_ma keywords for each i and m.        */

   /* Alternative header keyvalues (see the prologue above).                */
   /*-----------------------------------------------------------------------*/
   int    altlin;		/* Alternative representations              */
d1319 55
a1373 57
   int    padding;		/* (Dummy inserted for alignment purposes.) */
   double *cd;			/* CDi_ja linear transformation matrix.     */
   double *crota;		/* CROTAia keyvalues for each coord axis.   */

   /* Auxiliary coordinate system information, not used by WCSLIB.          */
   char   alt[4];
   int    colnum;
   int    *colax;

   char   (*cname)[72];
   double *crder;
   double *csyer;
   char   dateavg[72];
   char   dateobs[72];
   double equinox;
   double mjdavg;
   double mjdobs;
   double obsgeo[3];
   char   radesys[72];
   char   specsys[72];
   char   ssysobs[72];
   char   ssyssrc[72];
   double velangl;
   double velosys;
   char   wcsname[72];
   double zsource;

   /* Coordinate lookup tables (see the prologue above).                    */
   /*-----------------------------------------------------------------------*/
   int    ntab;			/* Number of separate tables.               */
   int    nwtb;			/* Number of wtbarr structs.                */
   struct tabprm *tab;		/* Tabular transformation parameters.       */
   struct wtbarr *wtb;		/* Array of wtbarr structs.                 */

   /* Information derived from the FITS header keyvalues by wcsset().       */
   /*-----------------------------------------------------------------------*/
   int    *types;		/* Coordinate type codes for each axis.     */
   char   lngtyp[8], lattyp[8];	/* Celestial axis types, e.g. RA, DEC.      */
   int    lng, lat, spec;	/* Longitude, latitude and spectral axis    */
                                /* indices (0-relative).                    */
   int    cubeface;		/* True if there is a CUBEFACE axis.        */

   struct linprm lin;		/* Linear    transformation parameters.     */
   struct celprm cel;		/* Celestial transformation parameters.     */
   struct spcprm spc;		/* Spectral  transformation parameters.     */

   int    m_flag, m_naxis;	/* The remainder are for memory management. */
   double *m_crpix, *m_pc, *m_cdelt, *m_crval;
   char  (*m_cunit)[72], (*m_ctype)[72];
   struct pvcard *m_pv;
   struct pscard *m_ps;
   double *m_cd, *m_crota;
   int    *m_colax;
   char  (*m_cname)[72];
   double *m_crder, *m_csyer;
   struct tabprm *m_tab;
   struct wtbarr *m_wtb;
d1376 1
d1380 10
a1389 2
int wcsnpv(int);
int wcsnps(int);
d1391 1
a1391 12
int wcsini(int, int, struct wcsprm *);
int wcssub(int, const struct wcsprm *, int *, int[], struct wcsprm *);
int wcsfree(struct wcsprm *);
int wcsprt(const struct wcsprm *);
int wcsset(struct wcsprm *);
int wcsp2s(struct wcsprm *, int, int, const double[],
           double[], double[], double[], double[], int[]);
int wcss2p(struct wcsprm *, int, int, const double[],
           double[], double[], double[], double[], int[]);
int wcsmix(struct wcsprm *, int, int, const double[], double, int,
           double[], double[], double[], double[], double[]);
int wcssptr(struct wcsprm *, int *, char [9]);
d1393 17
d1413 11
@


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: wcs.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: wcs.h,v 4.3.1.1 2007/12/27 13:23:47 cal103 Exp cal103 $
d51 2
a52 2
*   Summary of the wcs routines
*   ---------------------------
d56 4
a59 4
*   struct (see below) which contains all information needed for the
*   computations.  The struct contains some members that must be set by the
*   caller, and others that are maintained by these routines, somewhat like a
*   C++ class but with no encapsulation.
d69 1
a69 1
*   explicitly - refer to the explanation of wcs.flag (see below).
d100 2
a101 2
*                        crpix, etc. arrays as explained in "Memory allocation
*                        and deallocation" (see below).
d163 5
a167 6
*                        in the destination as explained in "Memory allocation
*                        and deallocation" (see below).  Otherwise, it is
*                        assumed that pointers to these arrays have been set
*                        by the caller except if they are null pointers in
*                        which case memory will be allocated for them
*                        regardless.
d200 1
a200 1
*                        Note 2 (see below) contains further usage notes.
d732 1
a732 1
*         otherwise it must be set by the caller.  See also wcsnpv().
d753 1
a753 1
*         otherwise it must be set by the caller.  See also wcsnps().
d1000 3
a1002 3
*         Indices into the imgcrd[][] and world[][] arrays (see above).  These
*         may also serve as indices into the pixcrd[][] array provided that
*         the PCi_ja matrix does not transpose axes.
d1042 1
a1042 1
*   the wcsprm struct as described in the usage notes (see above).
@


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: wcs.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 769
a811 67
*   "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.
*
*
* Summary of the wcs routines
* ---------------------------
* These routines implement the FITS World Coordinate System (WCS) standard
* which defines methods to be used for computing world coordinates from image
* pixel coordinates, and vice versa.  They are based on the wcsprm struct
* which contains all information needed for the computations.  The struct
* contains some members that must be set by the user, and others that are
* maintained by these routines, somewhat like a C++ class but with no
* encapsulation.
*
* Three routines, wcsini(), wcssub(), and wcsfree() are provided to manage the
* wcsprm struct and another, wcsprt(), to prints its contents.  Refer to the
* description of the wcsprm struct for an explanation of the anticipated usage
* of these routines.  wcscopy(), which does a deep copy of one wcsprm struct
* to another, is defined as a preprocessor macro function that invokes
* wcssub().
*
* A setup routine, wcsset(), computes intermediate values in the wcsprm struct
* from parameters in it that were supplied by the user.  The struct always
* needs to be set up by wcsset() but this need not be called explicitly -
* refer to the explanation of wcsprm::flag.
*
* wcsp2s() and wcss2p() implement the WCS world coordinate transformations.
* In fact, they are high level driver routines for the WCS linear,
* logarithmic, celestial, spectral and tabular transformation routines
* described in lin.h, log.h, cel.h, spc.h and tab.h.
*
* Given either the celestial longitude or latitude plus an element of the
* pixel coordinate a hybrid routine, wcsmix(), iteratively solves for the
* unknown elements.
*
* wcssptr() translates the spectral axis in a wcsprm struct.  For example, a
* 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
*
* Quadcube projections:
* ---------------------
*   The quadcube projections (TSC, CSC, QSC) may be represented in FITS in
*   either of two ways:
*
*     a: The six faces may be laid out in one plane and numbered as follows:
*
=                                 0
=
=                        4  3  2  1  4  3  2
=
=                                 5
*
*        Faces 2, 3 and 4 may appear on one side or the other (or both).  The
*        world-to-pixel routines map faces 2, 3 and 4 to the left but the
*        pixel-to-world routines accept them on either side.
*
*     b: The "COBE" convention in which the six faces are stored in a
*        three-dimensional structure using a CUBEFACE axis indexed from
*        0 to 5 as above.
*
*   These routines support both methods; wcsset() determines which is being
*   used by the presence or absence of a CUBEFACE axis in ctype[].  wcsp2s()
*   and wcss2p() translate the CUBEFACE axis representation to the single
*   plane representation understood by the lower-level WCSLIB projection
d814 261
a1075 458
* wcsini() - Default constructor for the wcsprm struct
* ----------------------------------------------------
* wcsini() optionally allocates memory for arrays in a wcsprm struct and sets
* all members of the struct to default values.  Memory is allocated for up to
* NPVMAX PVi_ma keywords or NPSMAX PSi_ma keywords per WCS representation.
* These may be changed via wcsnpv() and wcsnps() before wcsini() is called.
*
* PLEASE NOTE: every wcsprm struct should be initialized by wcsini(), possibly
* repeatedly.  On the first invokation, and only the first invokation,
* wcsprm::flag must be set to -1 to initialize memory management, regardless
* of whether wcsini() will actually be used to allocate memory.
*
* Given:
*   alloc     int       If true, allocate memory unconditionally for the
*                       crpix, etc. arrays.
*
*                       If false, it is assumed that pointers to these arrays
*                       have been set by the user except if they are null
*                       pointers in which case memory will be allocated for
*                       them regardless.  (In other words, setting alloc true
*                       saves having to initalize these pointers to zero.)
*
*   naxis     int       The number of world coordinate axes.  This is used to
*                       determine the length of the various wcsprm vectors and
*                       matrices and therefore the amount of memory to
*                       allocate for them.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
*                       Note that, in order to initialize memory management,
*                       wcsprm::flag should be set to -1 when wcs is
*                       initialized for the first time (memory leaks may
*                       result if it had already been initialized).
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*
*
* wcsnpv() - Memory allocation for PVi_ma
* ---------------------------------------
* wcsnpv() changes the value of NPVMAX (default 64).  This global variable
* controls the number of PVi_ma keywords that wcsini() should allocate space
* for.
*
* PLEASE NOTE: This function is not thread-safe.
*
* Given:
*   n         int       Value of NPVMAX; ignored if < 0.
*
* Function return value:
*             int       Current value of NPVMAX.
*
*
* wcsnps() - Memory allocation for PSi_ma
* ---------------------------------------
* wcsnps() changes the values of NPSMAX (default 8).  This global variable
* controls the number of PSi_ma keywords that wcsini() should allocate space
* for.
*
* PLEASE NOTE: This function is not thread-safe.
*
* Given:
*   n         int       Value of NPSMAX; ignored if < 0.
*
* Function return value:
*             int       Current value of NPSMAX.
*
*
* wcssub() - Subimage extraction routine for the wcsprm struct
* ------------------------------------------------------------
* wcssub() extracts the coordinate description for a subimage from a wcsprm
* struct.  It does a deep copy, using wcsini() to allocate memory for its
* arrays if required.  Only the "information to be provided" part of the
* struct is extracted; a call to wcsset() is required to set up the remainder.
*
* The world coordinate system of the subimage must be separable in the sense
* that the world coordinates at any point in the subimage must depend only on
* the pixel coordinates of the axes extracted.  In practice, this means that
* the PCi_ja matrix of the original image must not contain non-zero
* off-diagonal terms that associate any of the subimage axes with any of the
* non-subimage axes.
*
* Note that while the required elements of the tabprm array are extracted, the
* wtbarr array is not.  (Thus it is not appropriate to call wcssub() after
* wcstab() but before filling the tabprm structs - refer to wcshdr.h.)
*
* Given:
*   alloc     int       If true, allocate memory for the crpix, etc. arrays in
*                       the destination.  Otherwise, it is assumed that
*                       pointers to these arrays have been set by the user
*                       except if they are null pointers in which case memory
*                       will be allocated for them regardless.
*
*   wcssrc    const struct wcsprm*
*                       Struct to extract from.
*
* Given and returned:
*   nsub      int*
*   axes      int[]     Vector of length *nsub containing the image axis
*                       numbers (1-relative) to extract.  Order is
*                       significant; axes[0] is the axis number of the input
*                       image that corresponds to the first axis in the
*                       subimage, etc.
*
*                       nsub (the pointer) may be set to zero, and so also may
*                       nsub, to indicate the number of axes in the input
*                       image; the number of axes will be returned if
*                       nsub != 0.  axes itself (the pointer) may be set to
*                       zero to indicate the first *nsub axes in their
*                       original order.
*
*                       Set both nsub and axes to zero to do a deep copy of
*                       one wcsprm struct to another.
*
*                       Subimage extraction by coordinate axis type may be
*                       done by setting the elements of axes[] to the
*                       following special preprocessor macro values:
*
*                         WCSSUB_LONGITUDE: Celestial longitude.
*                         WCSSUB_LATITUDE:  Celestial latitude.
*                         WCSSUB_CUBEFACE:  Quadcube CUBEFACE axis.
*                         WCSSUB_SPECTRAL:  Spectral axis.
*                         WCSSUB_STOKES:    Stokes axis.
*
*                       Refer to the notes (below) for further usage examples.
*
*                       On return, *nsub will contain the number of axes in
*                       the subimage; this may be zero if there were no axes
*                       of the required type(s) (in which case no memory will
*                       be allocated).  axes[] will contain the axis numbers
*                       that were extracted.  The vector length must be
*                       sufficient to contain all axis numbers.  No checks are
*                       performed to verify that the coordinate axes are
*                       consistent, this is done by wcsset().
*
*   wcsdst    struct wcsprm*
*                       Struct describing the subimage.  wcsprm::flag should
*                       be set to -1 if wcsdst was not previously initialized
*                       (memory leaks may result if it was previously
*                       initialized).
*
* Function return value:
*             int       Status return value:
*                          0: Success.
*                          1: Null wcsprm pointer passed.
*                          2: Memory allocation failed.
*                         12: Invalid subimage specification.
*                         13: Non-separable subimage coordinate system.
*
* Notes:
*   Combinations of subimage axes of particular types may be extracted in the
*   same order as they occur in the input image by combining preprocessor
*   codes, for example
*
=     *nsub = 1;
=     axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
*
*   would extract the longitude, latitude, and spectral axes in the same order
*   as the input image.  If one of each were present, *nsub = 3 would be
*   returned.
*
*   For convenience, WCSSUB_CELESTIAL is defined as the combination
*   WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
*
*   The codes may also be negated to extract all but the types specified, for
*   example
*
=     *nsub = 4;
=     axes[0] = WCSSUB_LONGITUDE;
=     axes[1] = WCSSUB_LATITUDE;
=     axes[2] = WCSSUB_CUBEFACE;
=     axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
*
*   The last of these specifies all axis types other than spectral or Stokes.
*   Extraction is done in the order specified by axes[] a longitude axis (if
*   present) would be extracted first (via axes[0]) and not subsequently (via
*   axes[3]).  Likewise for the latitude and cubeface axes in this example.
*
*   From the foregoing, it is apparent that the value of *nsub returned may be
*   less than or greater than that given.  However, it will never exceed the
*   number of axes in the input image.
*
*
* wcscopy() macro - Copy routine for the wcsprm struct
* ----------------------------------------------------
* wcscopy() does a deep copy of one wcsprm struct to another.  As of
* WCSLIB 3.6, it is implemented as a preprocessor macro that invokes
* wcssub() with the nsub and axes pointers both set to zero.
*
*
* wcsfree() - Destructor for the wcsprm struct
* --------------------------------------------
* wcsfree() frees memory allocated for the wcsprm arrays by wcsini() and/or
* wcsset().  wcsini() records the memory it allocates and wcsfree() will only
* attempt to free this.
*
* PLEASE NOTE: wcsfree() must not be invoked on a wcsprm struct that was not
* initialized by wcsini().
*
* Returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsprt() - Print routine for the wcsprm struct
* ----------------------------------------------
* wcsprt() prints the contents of a wcsprm struct.
*
* Given:
*   wcs       const struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*
*
* wcsset() - Setup routine for the wcsprm struct
* ----------------------------------------------
* wcsset() sets up a wcsprm struct according to information supplied within
* it (refer to the description of the wcsprm struct).
*
* wcsset() recognizes the NCP projection and converts it to the equivalent SIN
* projection and it also recognizes GLS as a synonym for SFL.  It does alias
* translation for the AIPS spectral types ('FREQ-LSR', 'FELO-HEL', etc.) but
* without changing the input header keywords.
*
* Note that this routine need not be called directly; it will be invoked by
* wcsp2s() and wcss2p() if the wcsprm::flag is anything other than a
* predefined magic value.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         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.
*
*
* wcsp2s() - Pixel-to-world transformation
* ----------------------------------------
* wcsp2s() transforms pixel coordinates to world coordinates.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Given:
*   ncoord,
*   nelem     int       The number of coordinates, each of vector length
*                       nelem but containing wcs.naxis coordinate elements.
*                       Thus nelem must equal or exceed the value of the
*                       NAXIS keyword unless ncoord == 1, in which case nelem
*                       is not used.
*   pixcrd    const double[ncoord][nelem]
*                       Array of pixel coordinates.
*
* Returned:
*   imgcrd    double[ncoord][nelem]
*                       Array of intermediate world coordinates.  For
*                       celestial axes, imgcrd[][wcs.lng] and
*                       imgcrd[][wcs.lat] are the projected x-, and
*                       y-coordinates in pseudo "degrees".  For spectral
*                       axes, imgcrd[][wcs.spec] is the intermediate spectral
*                       coordinate, in SI units.
*
*   phi,theta double[ncoord]
*                       Longitude and latitude in the native coordinate system
*                       of the projection [deg].
*
*   world     double[ncoord][nelem]
*                       Array of world coordinates.  For celestial axes,
*                       world[][wcs.lng] and world[][wcs.lat] are the
*                       celestial longitude and latitude [deg].  For
*                       spectral axes, imgcrd[][wcs.spec] is the intermediate
*                       spectral coordinate, in SI units.
*
*   stat      int[ncoord]
*                       Status return value for each coordinate:
*                         0: Success.
*                         1: Invalid pixel coordinate.
*
* Function return value:
*             int       Status return value:
*                         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.
*                         8: One or more of the pixel coordinates were
*                            invalid, as indicated by the stat vector.
*
*
* wcss2p() - World-to-pixel transformation
* ----------------------------------------
* wcss2p() transforms world coordinates to pixel coordinates.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Given:
*   ncoord,
*   nelem     int       The number of coordinates, each of vector length nelem
*                       but containing wcs.naxis coordinate elements.  Thus
*                       nelem must equal or exceed the value of the NAXIS
*                       keyword unless ncoord == 1, in which case nelem is not
*                       used.
*   world     const double[ncoord][nelem]
*                       Array of world coordinates.  For celestial axes,
*                       world[][wcs.lng] and world[][wcs.lat] are the
*                       celestial longitude and latitude [deg]. For spectral
*                       axes, world[][wcs.spec] is the spectral coordinate, in
*                       SI units.
*
* Returned:
*   phi,theta double[ncoord]
*                       Longitude and latitude in the native coordinate
*                       system of the projection [deg].
*
*   imgcrd    double[ncoord][nelem]
*                       Array of intermediate world coordinates.  For
*                       celestial axes, imgcrd[][wcs.lng] and
*                       imgcrd[][wcs.lat] are the projected x-, and
*                       y-coordinates in pseudo "degrees".  For quadcube
*                       projections with a CUBEFACE axis the face number is
*                       also returned in imgcrd[][wcs.cubeface].  For
*                       spectral axes, imgcrd[][wcs.spec] is the intermediate
*                       spectral coordinate, in SI units.
*
*   pixcrd    double[ncoord][nelem]
*                       Array of pixel coordinates.
*
*   stat      int[ncoord]
*                       Status return value for each coordinate:
*                         0: Success.
*                         1: Invalid world coordinate.
*
* Function return value:
*             int       Status return value:
*                         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.
*                         9: One or more of the world coordinates were
*                            invalid, as indicated by the stat vector.
*
*
* wcsmix() - Hybrid coordinate transformation
* -------------------------------------------
* wcsmix(), given either the celestial longitude or latitude plus an element
* of the pixel coordinate, solves for the remaining elements by iterating on
* the unknown celestial coordinate element using wcss2p().  Refer also to the
* notes below.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Indices for the celestial coordinates obtained
*                       by parsing the wcsprm::ctype[].
*
* Given:
*   mixpix    int       Which element of the pixel coordinate is given.
*   mixcel    int       Which element of the celestial coordinate is given:
*                         1: Celestial longitude is given in
*                            world[wcs.lng], latitude returned in
*                            world[wcs.lat].
*                         2: Celestial latitude is given in
*                            world[wcs.lat], longitude returned in
*                            world[wcs.lng].
*
*   vspan     const double[2]
*                       Solution interval for the celestial coordinate [deg].
*                       The ordering of the two limits is irrelevant.
*                       Longitude ranges may be specified with any convenient
*                       normalization, for example [-120,+120] is the same as
*                       [240,480], except that the solution will be returned
*                       with the same normalization, i.e. lie within the
*                       interval specified.
*
*   vstep     const double
*                       Step size for solution search [deg].  If zero, a
*                       sensible, although perhaps non-optimal default will be
*                       used.
*
*   viter     int       If a solution is not found then the step size will be
*                       halved and the search recommenced.  viter controls how
*                       many times the step size is halved.  The allowed range
*                       is 5 - 10.
*
* Given and returned:
*   world     double[naxis]
*                       World coordinate elements.  world[wcs.lng] and
*                       world[wcs.lat] are the celestial longitude and
*                       latitude [deg].  Which is given and which returned
*                       depends on the value of mixcel.  All other elements
*                       are given.
*
* Returned:
*   phi,theta double[naxis]
*                       Longitude and latitude in the native coordinate
*                       system of the projection [deg].
*
*   imgcrd    double[naxis]
*                       Image coordinate elements.  imgcrd[wcs.lng] and
*                       imgcrd[wcs.lat] are the projected x-, and
*                       y-coordinates in pseudo "degrees".
*
* Given and returned:
*   pixcrd    double[naxis]
*                       Pixel coordinate.  The element indicated by mixpix is
*                       given and the remaining elements are returned.
*
* Function return value:
*             int       Status return value:
*                          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.
*                         10: Invalid world coordinate.
*                         11: No solution found in the specified interval.
d1077 2
a1078 1
* Notes:
d1087 4
a1090 4
*   within the specified solution interval then a search is made for a
*   "non-crossing" solution as may arise from a point of tangency.  The
*   process is complicated by having to make allowance for the discontinuities
*   that occur in all map projections.
d1095 4
a1098 4
*   Note the circumstance that arises when the solution point lies at a native
*   pole of a projection in which the pole is represented as a finite curve,
*   for example the zenithals and conics.  In such cases two or more valid
*   solutions may exist but wcsmix() only ever returns one.
a1104 624
*
* wcssptr() - Spectral axis translation
* -------------------------------------
* wcssptr() translates the spectral axis in a wcsprm struct.  For example, a
* 'FREQ' axis may be translated into 'ZOPT-F2W' and vice versa.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*   i         int*      Index of the spectral axis (0-relative).  If given < 0
*                       it will be set to the first spectral axis identified
*                       from the ctype[] keyvalues in the wcsprm struct.
*   ctype     char[9]   Required spectral CTYPEia.  Wildcarding may be used as
*                       for the ctypeS2 argument to spctrn() as described in
*                       the prologue of spc.h, i.e. if the final three
*                       characters are specified as "???", or if just the
*                       eighth character is specified as '?', the correct
*                       algorithm code will be substituted and returned.
*
* Function return value:
*             int       Status return value:
*                          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.
*                         12: Invalid subimage specification (no spectral
*                             axis).
*
*
* wcsprm struct - Coordinate transformation parameters
* ----------------------------------------------------
* The wcsprm struct contains information required to transform world
* coordinates.  It consists of certain members that must be set by the user
* ("given") and others that are set by the WCSLIB routines ("returned").
* Some of the former are not actually required for transforming coordinates.
* These are described as "auxiliary"; the struct simply provides a place to
* store them, though they may be used by wcshdo() in constructing a FITS
* header from a wcsprm struct.  Some of the returned values are supplied for
* informational purposes and others are for internal use only as indicated.
*
* In practice, it is expected that a WCS parser would scan the FITS header to
* determine the number of coordinate axes.  It would then use wcsini() to
* allocate memory for arrays in the wcsprm struct and set default values.
* Then as it reread the header and identified each WCS keyrecord it would load
* the value into the relevant wcsprm array element.  This is essentially what
* wcspih() does - refer to the prologue of wcshdr.h.  As the final step,
* wcsset() is invoked, either directly or indirectly, to set the derived
* members of the wcsprm struct.  wcsset() strips off trailing blanks in all
* string members and null-fills the character array.
*
*   int flag
*     (Given and returned) This flag must be set to zero whenever any of the
*     following wcsprm struct members are set or changed:
*
*       - wcsprm::naxis (q.v., not normally set by the user),
*       - wcsprm::crpix,
*       - wcsprm::pc,
*       - wcsprm::cdelt,
*       - wcsprm::crval,
*       - wcsprm::cunit,
*       - wcsprm::ctype,
*       - wcsprm::lonpole,
*       - wcsprm::latpole,
*       - wcsprm::restfrq,
*       - wcsprm::restwav,
*       - wcsprm::npv,
*       - wcsprm::pv,
*       - wcsprm::nps,
*       - wcsprm::ps,
*       - wcsprm::cd,
*       - wcsprm::crota,
*       - wcsprm::altlin.
*
*     This signals the initialization routine, wcsset(), to recompute the
*     returned members of the celprm struct.  celset() will reset flag to
*     indicate that this has been done.
*
*     PLEASE NOTE: flag should be set to -1 when wcsini() is called for the
*     first time for a particular wcsprm struct in order to initialize memory
*     management.  It must ONLY be used on the first initialization otherwise
*     memory leaks may result.
*
*   int naxis
*     (Given or returned) Number of pixel and world coordinate elements.
*
*     If wcsini() is used to initialize the linprm struct (as would normally
*     be the case) then it will set naxis from the value passed to it as a
*     function argument.  The user should not subsequently modify it.
*
*   double *crpix
*     (Given) Address of the first element of an array of double containing
*     the coordinate reference pixel, CRPIXja.
*
*   double *pc
*     (Given) Address of the first element of the PCi_ja (pixel coordinate)
*     transformation matrix.  The expected order is
*
=       struct wcsprm wcs;
=       wcs.pc = {PC1_1, PC1_2, PC2_1, PC2_2};
*
*     This may be constructed conveniently from a 2-D array via
*
=       double m[2][2] = {{PC1_1, PC1_2},
=                         {PC2_1, PC2_2}};
*
*     which is equivalent to
*
=       double m[2][2];
=       m[0][0] = PC1_1;
=       m[0][1] = PC1_2;
=       m[1][0] = PC2_1;
=       m[1][1] = PC2_2;
*
*     The storage order for this 2-D array is the same as for the 1-D array,
*     whence
*
=       wcs.pc = *m;
*
*     would be legitimate.
*
*   double *cdelt
*     (Given) Address of the first element of an array of double containing
*     the coordinate increments, CDELTia.
*
*   double *crval
*     (Given) Address of the first element of an array of double containing
*     the coordinate reference values, CRVALia.
*
*   char (*cunit)[72]
*     (Given) Address of the first element of an array of char[72] containing
*     the CUNITia keyvalues which define the units of measurement of the
*     CRVALia, CDELTia, and CDi_ja keywords.
*
*     As CUNITia is an optional header keyword, cunit[][72] may be left blank
*     but otherwise is expected to contain a standard units specification as
*     defined by WCS Paper I.  Utility function wcsutrn(), described in
*     wcsunits.h, is available to translate commonly used non-standard units
*     specifications but this must be done as a separate step before invoking
*     wcsset().
*
*     For celestial axes, if cunit[][72] is not blank, wcsset() uses
*     wcsunits() to parse it and scale cdelt[], crval[], and cd[][*] to
*     degrees.  It then resets cunit[][72] to "deg".
*
*     For spectral axes, if cunit[][72] is not blank, wcsset() uses wcsunits()
*     to parse it and scale cdelt[], crval[], and cd[][*] to SI units.  It
*     then resets cunit[][72] accordingly.
*
*     wcsset() ignores cunit[][72] for other coordinate types; cunit[][72] may
*     be used to label coordinate values.
*
*     These variables accomodate the longest allowed string-valued FITS
*     keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*   char (*ctype)[72]
*     (Given) Address of the first element of an array of char[72] containing
*     the coordinate axis types, CTYPEia.
*
*     The ctype[][72] keyword values must be in upper case and there must be
*     zero or one pair of matched celestial axis types, and zero or one
*     spectral axis.  The ctype[][72] strings should be padded with blanks on
*     the right and null-terminated so that they are at least eight characters
*     in length.
*
*     These variables accomodate the longest allowed string-valued FITS
*     keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*   double lonpole
*     (Given and returned) The native longitude of the celestial pole, phi_p,
*     given by LONPOLEa [deg] or by PVi_2a [deg] attached to the longitude
*     axis which takes precedence if defined, and ...
*   double latpole
*     (Given and returned) ... the native latitude of the celestial pole,
*     theta_p, given by LATPOLEa [deg] or by PVi_3a [deg] attached to the
*     longitude axis which takes precedence if defined.
*
*     lonpole and latpole may be left to default to values set by wcsini()
*     (see celprm::ref), but in any case they will be reset by wcsset() to
*     the values actually used.  Note therefore that if the wcsprm struct is
*     reused without resetting them, whether directly or via wcsini(), they
*     will no longer have their default values.
*
*   double restfrq
*     (Given) The rest frequency [Hz], and/or ...
*   double restwav
*     (Given) ... the rest wavelength in vacuuo [m], only one of which need be
*     given, the other should be set to zero.
*
*   int npv
*     (Given) The number of entries in the wcsprm::pv[] array.
*
*   int npvmax
*     (Given or returned) The length of the wcsprm::pv[] array.
*
*     npvmax will be set by wcsini() if it allocates memory for wcsprm::pv[],
*     otherwise it must be set by the user.  See also wcsnpv().
*
*   struct pvcard *pv
*     (Given or returned) Address of the first element of an array of length
*     npvmax of pvcard structs.  Set by wcsini() if it allocates memory for
*     pv[], otherwise it must be set by the user.  See also wcsnpv().
*
*     As a FITS header parser encounters each PVi_ma keyword it should load it
*     into a pvcard struct in the array and increment npv.  wcsset()
*     interprets these as required.
*
*     Note that, if they were not given, wcsset() resets the entries for
*     PVi_1a, PVi_2a, PVi_3a, and PVi_4a for longitude axis i to match
*     (phi_0,theta_0), the native longitude and latitude of the reference
*     point given by LONPOLEa and LATPOLEa.
*
*   int nps
*     (Given) The number of entries in the wcsprm::ps[] array.
*
*   int npsmax
*     (Given or returned) The length of the wcsprm::ps[] array.
*
*     npsmax will be set by wcsini() if it allocates memory for wcsprm::ps[],
*     otherwise it must be set by the user.  See also wcsnps().
*
*   struct pscard *ps
*     (Given or returned) Address of the first element of an array of length
*     npsmax of pscard structs.  Set by wcsini() if it allocates memory for
*     ps[], otherwise it must be set by the user.  See also wcsnps().
*
*     As a FITS header parser encounters each PSi_ma keyword it should load it
*     into a pscard struct in the array and increment nps.  wcsset()
*     interprets these as required (currently no PSi_ma keyvalues are
*     recognized).
*
*   double *cd
*     (Given) For historical compatibility, the wcsprm struct supports two
*     alternate specifications of the linear transformation matrix, those
*     associated with the CDi_ja keywords, and ...
*   double *crota
*     (Given) ... those associated with the CROTAia keywords.  Although these
*     may not formally co-exist with PCi_ja, the approach taken here is simply
*     to ignore them if given in conjunction with PCi_ja.
*
*   int altlin
*     (Given) altlin is a bit flag that denotes which of the PCi_ja, CDi_ja
*     and CROTAia keywords are present in the header:
*
*     - Bit 0: PCi_ja is present.
*
*     - Bit 1: CDi_ja is present.
*
*       Matrix elements in the IRAF convention are
*       equivalent to the product CDi_ja = CDELTia * PCi_ja, but the
*       defaults differ from that of the PCi_ja matrix.  If one or more
*       CDi_ja keywords are present then all unspecified CDi_ja default to
*       zero.  If no CDi_ja (or CROTAia) keywords are present, then the
*       header is assumed to be in PCi_ja form whether or not any PCi_ja
*       keywords are present since this results in an interpretation of
*       CDELTia consistent with the original FITS specification.
*
*       While CDi_ja may not formally co-exist with PCi_ja, it may co-exist
*       with CDELTia and CROTAia which are to be ignored.
*
*     - Bit 2: CROTAia is present.
*
*       In the AIPS convention, CROTAia may only be
*       associated with the latitude axis of a celestial axis pair.  It
*       specifies a rotation in the image plane that is applied AFTER the
*       CDELTia; any other CROTAia keywords are ignored.
*
*       CROTAia may not formally co-exist with PCi_ja.
*
*       CROTAia and CDELTia may formally co-exist with CDi_ja but if so are to
*       be ignored.
*
*     CDi_ja and CROTAia keywords, if found, are to be stored in the
*     wcsprm::cd and wcsprm::crota arrays which are dimensioned similarly to
*     wcsprm::pc and wcsprm::cdelt.  FITS
*     header parsers should use the following procedure:
*
*     - Whenever a PCi_ja  keyword is encountered: altlin |= 1;
*
*     - Whenever a CDi_ja  keyword is encountered: altlin |= 2;
*
*     - Whenever a CROTAia keyword is encountered: altlin |= 4;
*
*     If none of these bits are set the PCi_ja representation results, i.e.
*     wcsprm::pc and wcsprm::cdelt will be used as given.
*
*     These alternate specifications of the linear transformation matrix are
*     translated immediately to PCi_ja by wcsset() and are invisible to the
*     lower-level WCSLIB routines.  In particular, wcsset() resets
*     wcsprm::cdelt to unity if CDi_ja is present (and no PCi_ja).
*
*     If CROTAia are present but none is associated with the latitude axis
*     (and no PCi_ja or CDi_ja), then wcsset() reverts to a unity PCi_ja
*     matrix.
*
*   int padding
*     (An unused variable inserted for alignment purposes only.)
*
*   char alt[4]
*     (Given, auxiliary) Character code for alternate coordinate descriptions
*     (i.e. the 'a' in keyword names such as CTYPEia).  This is blank for the
*     primary coordinate description, or one of the 26 upper-case letters,
*     A-Z.
*
*     An array of four characters is provided for alignment purposes, only the
*     first is used.
*
*   int colnum
*     (Given, auxiliary) Where the coordinate representation is associated
*     with an image-array column in a FITS binary table, this variable may be
*     used to record the relevant column number.
*
*     It should be set to zero for an image header or pixel list.
*
*   int *colax
*     (Given, auxiliary) Address of the first element of an array of int
*     recording the column numbers for each axis in a pixel list.
*
*     The array elements should be set to zero for an image header or image
*     array in a binary table.
*
*   char (*cname)[72]
*     (Given, auxiliary) The address of the first element of an array of
*     char[72] containing the coordinate axis names, CNAMEia.
*
*     These variables accomodate the longest allowed string-valued FITS
*     keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*   double *crder
*     (Given, auxiliary) Address of the first element of an array of double
*     recording the random error in the coordinate value, CRDERia.
*   double *csyer
*     (Given, auxiliary) Address of the first element of an array of double
*     recording the systematic error in the coordinate value, CSYERia.
*
*   char dateavg[72]
*     (Given, auxiliary) The date of a representative mid-point of the
*     observation in ISO format, yyyy-mm-ddThh:mm:ss.
*   char dateobs[72]
*     (Given, auxiliary) The date of the start of the observation unless
*     otherwise explained in the comment field of the DATE-OBS keyword, in
*     ISO format, yyyy-mm-ddThh:mm:ss.
*
*   double equinox
*     (Given, auxiliary) The equinox associated with dynamical equatorial or
*     ecliptic coordinate systems, EQUINOXa (or EPOCH in older headers).  Not
*     applicable to ICRS equatorial or ecliptic coordinates.
*
*   double mjdavg
*     (Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-AVG,
*     corresponding to DATE-AVG.
*   double mjdobs
*     (Given, auxiliary) Modified Julian Date (MJD = JD - 2400000.5), MJD-OBS,
*     corresponding to DATE-OBS.
*
*   double obsgeo[3]
*     (Given, auxiliary) Location of the observer in a standard terrestrial
*     reference frame, OBSGEO-X, OBSGEO-Y, OBSGEO-Z [m].
*
*   char radesys[72]
*     (Given, auxiliary) The equatorial or ecliptic coordinate system type,
*     RADESYSa.
*
*   char specsys[72]
*     (Given, auxiliary) Spectral reference frame (standard of rest),
*     SPECSYSa, and ...
*   char ssysobs[72]
*     (Given, auxiliary) ... the actual frame in which there is no
*     differential variation in the spectral coordinate across the
*     field-of-view, SSYSOBSa.
*   double velosys
*     (Given, auxiliary) The relative radial velocity [m/s] between the
*     observer and the selected standard of rest in the direction of the
*     celestial reference coordinate, VELOSYSa.
*
*   double zsource
*     (Given, auxiliary) The redshift, ZSOURCEa, of the source, and ...
*   char ssyssrc[72]
*     (Given, auxiliary) ... the spectral reference frame (standard of rest)
*     in which this was measured, SSYSSRCa.
*
*   double velangl
*     (Given, auxiliary) The angle [deg] that should be used to decompose an
*     observed velocity into radial and transverse components.
*
*   char wcsname[72]
*     (Given, auxiliary) The name given to the coordinate representation,
*     WCSNAMEa.  This variable accomodates the longest allowed string-valued
*     FITS keyword, being limited to 68 characters, plus the null-terminating
*     character.
*
*   int ntab
*     (Given) See wcsprm::tab.
*
*   int nwtb
*     (Given) See wcsprm::wtb.
*
*   struct tabprm *tab
*     (Given) Address of the first element of an array of ntab tabprm structs
*     for which memory has been allocated.  These are used to store tabular
*     transformation parameters.
*
*     Although technically wcsprm::ntab and tab are "given", they will
*     normally be set by invoking wcstab(), whether directly or indirectly.
*
*     The tabprm structs contain some members that must be supplied and others
*     that are derived.  The information to be supplied comes primarily from
*     arrays stored in one or more FITS binary table extensions.  These
*     arrays, referred to here as "wcstab arrays", are themselves located by
*     parameters stored in the FITS image header.
*
*   struct wtbarr *wtb
*     (Given) Address of the first element of an array of nwtb wtbarr structs
*     for which memory has been allocated.  These are used in extracting
*     wcstab arrays from a FITS binary table.
*
*     Although technically wcsprm::nwtb and wtb are "given", they will
*     normally be set by invoking wcstab(), whether directly or indirectly.
*
*   int *types
*     (Returned) Address of the first element of an array of int containing a
*     four-digit type code for each axis.
*
*     - First digit (i.e. 1000s):
*       - 0: Non-specific coordinate type.
*       - 1: Stokes coordinate.
*       - 2: Celestial coordinate (including CUBEFACE).
*       - 3: Spectral coordinate.
*
*     - Second digit (i.e. 100s):
*       - 0: Linear axis.
*       - 1: Quantized axis (STOKES, CUBEFACE).
*       - 2: Non-linear celestial axis.
*       - 3: Non-linear spectral axis.
*       - 4: Logarithmic axis.
*       - 5: Tabular axis.
*
*     - Third digit (i.e. 10s):
*       - 0: Group number, e.g. lookup table number, being an index into the
*            tabprm array (see above).
*
*     - The fourth digit is used as a qualifier depending on the axis type.
*
*       - For celestial axes:
*         - 0: Longitude coordinate.
*         - 1: Latitude coordinate.
*         - 2: CUBEFACE number.
*
*       - For lookup tables: the axis number in a multidimensional table.
*
*     CTYPEia in "4-3" form with unrecognized algorithm code will have its
*     type set to -1 and generate an error.
*
*   char lngtyp[8]
*     (Returned) Four-character WCS celestial longitude and ...
*   char lattyp[8]
*     (Returned) ... latitude axis types. e.g. "RA", "DEC", "GLON", "GLAT",
*     etc. extracted from 'RA--', 'DEC-', 'GLON', 'GLAT', etc. in the first
*     four characters of CTYPEia but with trailing dashes removed.  (Declared
*     as char[8] for alignment reasons.)
*
*   int lng
*     (Returned) Index for the longitude coordinate, and ...
*   int lat
*     (Returned) ... index for the latitude coordinate, and ...
*   int spec
*     (Returned) ... index for the spectral coordinate in the imgcrd[][] and
*     world[][] arrays in the API of wcsp2s(), wcss2p() and wcsmix().
*
*     These may also serve as indices into the pixcrd[][] array provided that
*     the PCi_ja matrix does not transpose axes.
*
*   int cubeface
*     (Returned) Index into the pixcrd[][] array for the CUBEFACE axis.  This
*     is used for quadcube projections where the cube faces are stored on a
*     separate axis (see wcs.h).
*
*   struct linprm lin
*     (Returned) Linear transformation parameters (usage is described in the
*     prologue to lin.h).
*
*   struct celprm cel
*     (Returned) Celestial transformation parameters (usage is described in
*     the prologue to cel.h).
*
*   struct spcprm spc
*     (Returned) Spectral transformation parameters (usage is described in the
*     prologue to spc.h).
*
*   int m_flag
*     (For internal use only.)
*   int m_naxis
*     (For internal use only.)
*   double *m_crpix
*     (For internal use only.)
*   double *m_pc
*     (For internal use only.)
*   double *m_cdelt
*     (For internal use only.)
*   double *m_crval
*     (For internal use only.)
*   char (*m_cunit)[72]
*     (For internal use only.)
*   char (*m_ctype)[72]
*     (For internal use only.)
*   struct pvcard *m_pv
*     (For internal use only.)
*   struct pscard *m_ps
*     (For internal use only.)
*   double *m_cd
*     (For internal use only.)
*   double *m_crota
*     (For internal use only.)
*   int *m_colax
*     (For internal use only.)
*   char (*m_cname)[72]
*     (For internal use only.)
*   double *m_crder
*     (For internal use only.)
*   double *m_csyer
*     (For internal use only.)
*   struct tabprm *m_tab
*     (For internal use only.)
*   struct wtbarr *m_wtb
*     (For internal use only.)
*
*
* pscard struct - Store for PSi_ma keyrecords
* -------------------------------------------
* The pscard struct is used to pass the parsed contents of PSi_ma keyrecords
* to wcsset() via the wcsprm struct.
*
* All members of this struct are to be set by the user.
*
*   int i
*     (Given) Axis number (1-relative), as in the FITS PSi_ma keyword.
*
*   int m
*     (Given) Parameter number (non-negative), as in the FITS PSi_ma keyword.
*
*   char value[72]
*     (Given) Parameter value.
*
*
* pvcard struct - Store for PVi_ma keyrecords
* -------------------------------------------
* The pvcard struct is used to pass the parsed contents of PVi_ma keyrecords
* to wcsset() via the wcsprm struct.
*
* All members of this struct are to be set by the user.
*
*   int i
*     (Given) Axis number (1-relative), as in the FITS PVi_ma keyword.
*
*   int m
*     (Given) Parameter number (non-negative), as in the FITS PVi_ma keyword.
*
*   double value
*     (Given) Parameter value.
*
*
* wtbarr struct - Extraction of coordinate lookup tables from BINTABLE
* --------------------------------------------------------------------
* Function wcstab(), which is invoked automatically by wcspih(), sets up an
* array of wtbarr structs to assist in extracting coordinate lookup tables
* from a binary table extension (BINTABLE) and copying them into the tabprm
* structs stored in wcsprm.  Refer to the usage notes for wcspih() and
* wcstab() in wcshdr.h, and also the prologue to tab.h.
*
* For C++ usage, because of a name space conflict with the wtbarr typedef
* defined in CFITSIO header fitsio.h, the wtbarr struct is renamed to wtbarr_s
* by preprocessor macro substitution with scope limited to wcs.h itself.
*
*   int i
*     (Given) Image axis number.
*
*   int m
*     (Given) wcstab array axis number for index vectors.
*
*   int kind
*     (Given) Character identifying the wcstab array type:
*       - c: coordinate array,
*       - i: index vector.
*
*   char extnam[72]
*     (Given) EXTNAME identifying the binary table extension.
*
*   int extver
*     (Given) EXTVER identifying the binary table extension.
*
*   int extlev
*     (Given) EXTLEV identifying the binary table extension.
*
*   char ttype[72]
*     (Given) TTYPEn identifying the column of the binary table that contains
*     the wcstab array.
*
*   long row
*     (Given) Table row number.
*
*   int ndim
*     (Given) Expected dimensionality of the wcstab array.
*
*   int *dimlen
*     (Given) Address of the first element of an array of int of length ndim
*     into which the wcstab array axis lengths are to be written.
*
*   double **arrayp
*     (Given) Pointer to an array of double which is to be allocated by the
*     user and into which the wcstab array is to be written.
*
*
* Global variable: const char *wcs_errmsg[] - Status return messages
* ------------------------------------------------------------------
* Error messages to match the status value returned from each function.
*
d1128 9
d1138 1
a1138 1
/* Struct used for storing PVi_ma keywords. */
d1140 3
a1142 3
  int i;			/* Axis number, as in PVi_ma (1-relative).  */
  int m;			/* Parameter number, ditto  (0-relative).   */
  double value;			/* Parameter value.                         */
d1145 1
a1145 1
/* Struct used for storing PSi_ma keywords. */
d1147 3
a1149 3
  int i;			/* Axis number, as in PSi_ma (1-relative).  */
  int m;			/* Parameter number, ditto  (0-relative).   */
  char value[72];		/* Parameter value.                         */
d1157 12
a1168 12
  int  i;			/* Image axis number.                       */
  int  m;			/* Array axis number for index vectors.     */
  int  kind;			/* wcstab array type.                       */
  char extnam[72];		/* EXTNAME of binary table extension.       */
  int  extver;			/* EXTVER  of binary table extension.       */
  int  extlev;			/* EXTLEV  of binary table extension.       */
  char ttype[72];		/* TTYPEn of column containing the array.   */
  long row;			/* Table row number.                        */
  int  ndim;			/* Expected wcstab array dimensionality.    */
  int  *dimlen;			/* Where to write the array axis lengths.   */
  double **arrayp;		/* Where to write the address of the array  */
				/* allocated to store the wcstab array.     */
d1173 32
a1204 34
  /* Initialization flag (see the prologue above).                          */
  /*------------------------------------------------------------------------*/
  int    flag;			/* Set to zero to force initialization.     */

  /* FITS header keyvalues to be provided (see the prologue above).         */
  /*------------------------------------------------------------------------*/
  int    naxis;			/* Number of axes (pixel and coordinate).   */
  double *crpix;		/* CRPIXja keyvalues for each pixel axis.   */
  double *pc;			/* PCi_ja  linear transformation matrix.    */
  double *cdelt;		/* CDELTia keyvalues for each coord axis.   */
  double *crval;		/* CRVALia keyvalues for each coord axis.   */

  char   (*cunit)[72];		/* CUNITia keyvalues for each coord axis.   */
  char   (*ctype)[72];		/* CTYPEia keyvalues for each coord axis.   */

  double lonpole;		/* LONPOLEa keyvalue.                       */
  double latpole;		/* LATPOLEa keyvalue.                       */

  double restfrq;		/* RESTFRQa keyvalue.                       */
  double restwav;		/* RESTWAVa keyvalue.                       */

  int    npv;			/* Number of PVi_ma keywords, and the       */
  int    npvmax;		/* number for which space was allocated.    */
  struct pvcard *pv;		/* PVi_ma keywords for each i and m.        */

  int    nps;			/* Number of PSi_ma keywords, and the       */
  int    npsmax;		/* number for which space was allocated.    */
  struct pscard *ps;		/* PSi_ma keywords for each i and m.        */

  /* Alternative header keyvalues (see the prologue above).                 */
  /*------------------------------------------------------------------------*/
  double *cd;			/* CDi_ja linear transformation matrix.     */
  double *crota;		/* CROTAia keyvalues for each coord axis.   */
  int    altlin;		/* Alternative representations              */
d1208 57
a1264 55
  int    padding;		/* (Dummy inserted for alignment purposes.) */

  /* Auxiliary coordinate system information, not used by WCSLIB.           */
  char   alt[4];
  int    colnum;
  int    *colax;

  char   (*cname)[72];
  double *crder;
  double *csyer;
  char   dateavg[72];
  char   dateobs[72];
  double equinox;
  double mjdavg;
  double mjdobs;
  double obsgeo[3];
  char   radesys[72];
  char   specsys[72];
  char   ssysobs[72];
  double velosys;
  double zsource;
  char   ssyssrc[72];
  double velangl;
  char   wcsname[72];

  /* Coordinate lookup tables (see the prologue above).                     */
  /*------------------------------------------------------------------------*/
  int    ntab;			/* Number of separate tables.               */
  int    nwtb;			/* Number of wtbarr structs.                */
  struct tabprm *tab;		/* Tabular transformation parameters.       */
  struct wtbarr *wtb;		/* Array of wtbarr structs.                 */

  /* Information derived from the FITS header keyvalues by wcsset().        */
  /*------------------------------------------------------------------------*/
  int    *types;		/* Coordinate type codes for each axis.     */
  char   lngtyp[8], lattyp[8];	/* Celestial axis types, e.g. RA, DEC.      */
  int    lng, lat, spec;	/* Longitude, latitude and spectral axis    */
				/* indices (0-relative).                    */
  int    cubeface;		/* True if there is a CUBEFACE axis.        */

  struct linprm lin;		/* Linear    transformation parameters.     */
  struct celprm cel;		/* Celestial transformation parameters.     */
  struct spcprm spc;		/* Spectral  transformation parameters.     */

  int    m_flag, m_naxis;	/* The remainder are for memory management. */
  double *m_crpix, *m_pc, *m_cdelt, *m_crval;
  char  (*m_cunit)[72], (*m_ctype)[72];
  struct pvcard *m_pv;
  struct pscard *m_ps;
  double *m_cd, *m_crota;
  int    *m_colax;
  char  (*m_cname)[72];
  double *m_crder, *m_csyer;
  struct tabprm *m_tab;
  struct wtbarr *m_wtb;
a1266 1
/* Size of the wcsprm struct in int units, used by the Fortran wrappers. */
d1270 2
a1271 10
int wcsnpv(int n);

int wcsnps(int n);

int wcsini(int alloc, int naxis, struct wcsprm *wcs);

int wcssub(int alloc, const struct wcsprm *wcssrc, int *nsub, int axes[],
           struct wcsprm *wcsdst);

int wcsfree(struct wcsprm *wcs);
d1273 12
a1284 1
int wcsprt(const struct wcsprm *wcs);
a1285 17
int wcsset(struct wcsprm *wcs);

int wcsp2s(struct wcsprm *wcs, int ncoord, int nelem, const double pixcrd[],
           double imgcrd[], double phi[], double theta[], double world[],
	   int stat[]);

int wcss2p(struct wcsprm *wcs, int ncoord, int nelem, const double world[],
           double phi[], double theta[], double imgcrd[], double pixcrd[],
	   int stat[]);

int wcsmix(struct wcsprm *wcs, int mixpix, int mixcel, const double vspan[],
           double vstep, int viter, double world[], double phi[],
	   double theta[], double imgcrd[], double pixcrd[]);

int wcssptr(struct wcsprm *wcs, int *i, char ctype[9]);

/* Defined mainly for backwards compatibility, use wcssub() instead. */
a1288 11
/* Deprecated. */
#define wcsini_errmsg wcs_errmsg
#define wcssub_errmsg wcs_errmsg
#define wcscopy_errmsg wcs_errmsg
#define wcsfree_errmsg wcs_errmsg
#define wcsprt_errmsg wcs_errmsg
#define wcsset_errmsg wcs_errmsg
#define wcsp2s_errmsg wcs_errmsg
#define wcss2p_errmsg wcs_errmsg
#define wcsmix_errmsg wcs_errmsg

@


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: wcs.h,v 4.1 2005/08/30 07:32:42 cal103 Exp cal103 $
d34 1
a34 1
*   WCSLIB 4.2 - C routines that implement the FITS World Coordinate System
d44 5
a48 2
*      Greisen, E.W., Valdes, F.G., Calabretta, M.R., & Allen, S.L. 2005, A&A,
*      (Paper III, in preparation)
d51 2
a52 2
*   Summary of routines
*   -------------------
d88 3
a90 3
*   up to NPVMAX PVi_ma cards or NPSMAX PSi_ma cards per WCS representation.
*   These *   may be changed via wcsnpv() and wcsnps() before wcsini() is
*   called.
d133 1
a133 1
*   PSi_ma cards that wcsini() should allocate space for.
d274 1
a274 1
*   etc.) but without changing the input header cards.
d505 1
a505 1
*                        from the ctype[] cards in the wcsprm struct.
d597 7
a603 6
*   header until it encountered the NAXIS (or WCSAXESa) card which must occur
*   near the start of the header before any of the WCS keywords.  It would
*   then use wcsini() to allocate memory for arrays in the wcsprm struct and
*   set default values.  Then as it read and identified each WCS header card
*   it would load the value into the relevant wcsprm array element.  This is
*   essentially what wcspih() does - refer to the prologue of wcshdr.h.
d621 1
a621 1
*         WCSAXESa keywords.
d663 2
a664 2
*         CUNITia cards which define the units of measurement of the CRVALia,
*         CDELTia, and CDi_ja cards.
d666 6
a671 6
*         As CUNITia is an optional header card, cunit[][72] may be left blank
*         but otherwise is expected to contain a standard units specification
*         as defined by WCS Paper I.  Utility function wcsutrn(), described in
*         wcsunits.h, is available to translate commonly used non-standard
*         units specifications but this must be done as a separate step before
*         invoking wcsset().
d727 3
a729 3
*         As a FITS header parser encounters each PVi_ma card it should load
*         it into a pvcard struct in the array and increment npv.  wcsset()
*         interprets these as required.
d747 4
a750 4
*         As a FITS header parser encounters each PSi_ma card it should load
*         it into a pscard struct in the array and increment nps.  wcsset()
*         interprets these as required (currently no PSi_ma cards are
*         recognized).
d760 1
a760 1
*         associated with the CDi_ja and CROTAia cards.  Although these may
d764 2
a765 2
*         altlin is a bit flag that denotes which of these cards are present
*         in the header:
d772 4
a775 4
*                or more CDi_ja cards are present then all unspecified CDi_ja
*                default to zero.  If no CDi_ja (or CROTAia) cards are
*                present, then the header is assumed to be in PCi_ja form
*                whether or not any PCi_ja cards are present since this
d785 1
a785 1
*                applied AFTER the CDELTia; any other CROTAia cards are
d792 6
a797 6
*         CDi_ja and CROTAia cards, if found, are to be stored in the cd and
*         crota arrays which are dimensioned similarly to pc and cdelt.  FITS
*         header parsers should use the following precedure:
*            Whenever a PCi_ja  card is encountered: altlin |= 1;
*            Whenever a CDi_ja  card is encountered: altlin |= 2;
*            Whenever a CROTAia card is encountered: altlin |= 4;
d809 3
a811 2
*   may contain a complete copy of all WCS cards associated with a particular
*   coordinate representation.  They are not used by any WCSLIB routines.
d826 8
a833 2
*         It should be set to zero for an image header, or a binary table for
*         which there is no association with a specific column.
a834 1
*      char wcsname[72]
d836 2
a837 3
*         The name given to the coordinate representation WCSNAMEa, and the
*         address of the first element of an array of char[72] containing the
*         coordinate axis names, CNAMEia.
d848 19
d868 1
a868 4
*      double equinox
*         The equatorial or ecliptic coordinate system type, RADESYSa, and for
*         the dynamical systems, the associated equinox, EQUINOXa (or EPOCH in
*         older headers).
d884 3
a886 3
*      double obsgeo[3]
*         Location of the observer in a standard terrestrial reference frame,
*         OBSGEO-X, OBSGEO-Y, OBSGEO-Z (in metres).
d888 4
a891 9
*      char dateobs[72], dateavg[72]
*         The date of observation in ISO format, yyyy-mm-ddThh:mm:ss.
*         DATE-OBS refers to the start of the observation unless otherwise
*         explained in the comment field of the DATE-OBS card, and DATE-AVG
*         refers to a representative mid-point of the observation.
*
*      double mjdobs, mjdavg
*         Modified Julian Date (MJD = JD - 2400000.5), MJD-OBS and MJD-AVG,
*         corresponding to DATE-OBS and DATE-AVG.
d905 5
d1041 2
a1042 2
*   cunit, ctype, pv, ps, cd, crota, cname, crder, and csyer arrays in the
*   wcsprm struct as described in the usage notes above.
d1137 1
a1137 1
				/* Struct used for storing PVi_ma cards.    */
d1144 1
a1144 1
				/* Struct used for storing PSi_ma cards.    */
d1152 3
d1176 1
a1176 1
   /* FITS header cards to be provided (see the prologue above).            */
d1179 1
a1179 1
   double *crpix;		/* CRPIXja cards for each pixel axis.       */
d1181 2
a1182 2
   double *cdelt;		/* CDELTia cards for each coordinate axis.  */
   double *crval;		/* CRVALia cards for each coordinate axis.  */
d1184 2
a1185 2
   char   (*cunit)[72];		/* CUNITia cards for each coordinate axis.  */
   char   (*ctype)[72];		/* CTYPEia cards for each coordinate axis.  */
d1187 2
a1188 2
   double lonpole;		/* LONPOLEa card.                           */
   double latpole;		/* LATPOLEa card.                           */
d1190 2
a1191 2
   double restfrq;		/* RESTFRQa card.                           */
   double restwav;		/* RESTWAVa card.                           */
d1193 1
a1193 1
   int    npv;			/* Number of PVi_ma cards, and the          */
d1195 1
a1195 1
   struct pvcard *pv;		/* PVi_ma cards for each i and m.           */
d1197 1
a1197 1
   int    nps;			/* Number of PSi_ma cards, and the          */
d1199 1
a1199 1
   struct pscard *ps;		/* PSi_ma cards for each i and m.           */
d1201 1
a1201 1
   /* Alternative header cards (see the prologue above).                    */
d1207 1
d1209 1
a1209 1
   double *crota;		/* CROTAia cards for each coordinate axis.  */
d1214 2
a1215 1
   char   wcsname[72];
d1219 6
a1225 1
   double equinox;
d1228 2
d1231 1
a1231 1
   char   ssyssrc[72];
a1232 5
   double obsgeo[3];
   char   dateobs[72];
   char   dateavg[72];
   double mjdobs;
   double mjdavg;
d1237 1
a1238 2

   int    nwtb;			/* Number of wtbarr structs.                */
d1241 1
a1241 1
   /* Information derived from the FITS header cards by wcsset().           */
a1247 1
   int    padding1;		/* (Dummy inserted for alignment purposes.) */
d1259 1
a1263 1
   int    padding2;		/* (Dummy inserted for alignment purposes.) */
d1289 2
a1290 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: wcs.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
@Rename wtbarr to wtbarr_s in C++ by preprocessor macro substitution limited
to wcs.h; added a note on wtbarr namespace issues in C++; updated reference
to Paper III.
@
text
@d4 1
a4 1
*   Copyright (C) 1995-2006, Mark Calabretta
d30 1
a30 1
*   $Id: wcs.h,v 4.2.1.1 2005/12/05 02:39:43 cal103 Exp cal103 $
d43 2
a44 2
*      Greisen, E.W., Valdes, F.G., Calabretta, M.R., & Allen, S.L.
*      2006, A&A, 446, 747 (Paper III)
a883 5
*   For C++ usage, because of a name space conflict with the wtbarr typedef
*   defined in CFITSIO header fitsio.h, the wtbarr struct is renamed to
*   wtbarr_s by preprocessor macro substitution with scope limited to wcs.h
*   itself.
*
a1125 3
#ifdef __cplusplus
#define wtbarr wtbarr_s		/* See prologue above.			    */
#endif
a1257 1
#undef wtbarr_s
@


4.2.1.3
log
@Fixed the #undef wtbarr, it was incorrectly trying to #undef wtbarr_s.
@
text
@d30 1
a30 1
*   $Id: wcs.h,v 4.2.1.2 2006/04/27 03:46:13 cal103 Exp cal103 $
d43 1
a43 1
*      Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
d1266 1
a1266 1
#undef wtbarr
@


4.2.1.4
log
@Removed an extraneous ';' following the closing '}' of the 'extern "C" {'
block provided for use in C++.
@
text
@d30 1
a30 1
*   $Id: wcs.h,v 4.2.1.3 2006/06/21 06:16:01 cal103 Exp cal103 $
d1267 1
a1267 1
}
@


4.2.1.5
log
@Added colax to the wcsprm struct to record the column numbers for each axis
in a pixel list.
@
text
@d4 1
a4 1
*   Copyright (C) 1995-2007, Mark Calabretta
d30 1
a30 1
*   $Id: wcs.h,v 4.2.1.4 2006/08/02 00:14:58 cal103 Exp cal103 $
d85 2
a86 1
*   These may be changed via wcsnpv() and wcsnps() before wcsini() is called.
d820 2
a821 8
*         It should be set to zero for an image header or pixel list.
*
*      int *colax
*         Address of the first element of an array of int recording the column
*         numbers for each axis in a pixel list.
*
*         The array elements should be set to zero for an image header or
*         image array in a binary table.
d1020 2
a1021 2
*   cunit, ctype, pv, ps, cd, crota, colax, cname, crder, and csyer arrays in
*   the wcsprm struct as described in the usage notes above.
a1191 1
   int    *colax;
a1235 1
   int    *m_colax;
d1240 1
@


4.2.1.6
log
@Reordered a couple of members of the wcsprm struct to get alignment on 64-bit
machines.  Note that the wtbarr struct is slightly misaligned but can't be
changed as it is tied to the CFITSIO library.
@
text
@d30 1
a30 1
*   $Id: wcs.h,v 4.2.1.5 2007/06/29 01:58:03 cal103 Exp cal103 $
a1190 1
   int    padding;		/* (Dummy inserted for alignment purposes.) */
d1218 2
a1220 1
   struct tabprm *tab;		/* Tabular transformation parameters.       */
d1230 1
@


4.2.1.7
log
@Replaced use of the obsolete term "card".
@
text
@d30 1
a30 1
*   $Id: wcs.h,v 4.2.1.6 2007/07/12 08:40:38 cal103 Exp cal103 $
d84 2
a85 3
*   up to NPVMAX PVi_ma keywords or NPSMAX PSi_ma keywords per WCS
*   representation.  These may be changed via wcsnpv() and wcsnps() before
*   wcsini() is called.
d128 1
a128 1
*   PSi_ma keywords that wcsini() should allocate space for.
d269 1
a269 1
*   etc.) but without changing the input header keywords.
d500 1
a500 1
*                        from the ctype[] keyvalues in the wcsprm struct.
d592 6
a597 7
*   header until it encountered the NAXIS (or WCSAXESa) keyword which must
*   occur near the start of the header before any of the WCS keywords.  It
*   would then use wcsini() to allocate memory for arrays in the wcsprm struct
*   and set default values.  Then as it read and identified each WCS header
*   keyword record it would load the value into the relevant wcsprm array
*   element.  This is essentially what wcspih() does - refer to the prologue
*   of wcshdr.h.
d615 1
a615 1
*         WCSAXESa keyvalues.
d657 2
a658 2
*         CUNITia keyvalues which define the units of measurement of the
*         CRVALia, CDELTia, and CDi_ja keywords.
d660 6
a665 6
*         As CUNITia is an optional header keyword, cunit[][72] may be left
*         blank but otherwise is expected to contain a standard units
*         specification as defined by WCS Paper I.  Utility function
*         wcsutrn(), described in wcsunits.h, is available to translate
*         commonly used non-standard units specifications but this must be
*         done as a separate step before invoking wcsset().
d721 3
a723 3
*         As a FITS header parser encounters each PVi_ma keyword it should
*         load it into a pvcard struct in the array and increment npv.
*         wcsset() interprets these as required.
d741 4
a744 4
*         As a FITS header parser encounters each PSi_ma keyword it should
*         load it into a pscard struct in the array and increment nps.
*         wcsset() interprets these as required (currently no PSi_ma keyvalues
*         are recognized).
d754 1
a754 1
*         associated with the CDi_ja and CROTAia keywords.  Although these may
d758 2
a759 2
*         altlin is a bit flag that denotes which of these keywords are
*         present in the header:
d766 4
a769 4
*                or more CDi_ja keywords are present then all unspecified
*                CDi_ja default to zero.  If no CDi_ja (or CROTAia) keywords
*                are present, then the header is assumed to be in PCi_ja form
*                whether or not any PCi_ja keywords are present since this
d779 1
a779 1
*                applied AFTER the CDELTia; any other CROTAia keywords are
d786 6
a791 6
*         CDi_ja and CROTAia keywords, if found, are to be stored in the cd
*         and crota arrays which are dimensioned similarly to pc and cdelt.
*         FITS header parsers should use the following precedure:
*            Whenever a PCi_ja  keyword is encountered: altlin |= 1;
*            Whenever a CDi_ja  keyword is encountered: altlin |= 2;
*            Whenever a CROTAia keyword is encountered: altlin |= 4;
d803 2
a804 3
*   may contain a complete copy of all WCS keywords associated with a
*   particular coordinate representation.  They are not used by any WCSLIB
*   routines.
d870 1
a870 1
*         explained in the comment field of the DATE-OBS keyword, and DATE-AVG
d1121 1
a1121 1
				/* Struct used for storing PVi_ma keywords. */
d1128 1
a1128 1
				/* Struct used for storing PSi_ma keywords. */
d1160 1
a1160 1
   /* FITS header keyvalues to be provided (see the prologue above).        */
d1163 1
a1163 1
   double *crpix;		/* CRPIXja keyvalues for each pixel axis.       */
d1165 2
a1166 2
   double *cdelt;		/* CDELTia keyvalues for each coord axis.   */
   double *crval;		/* CRVALia keyvalues for each coord axis.   */
d1168 2
a1169 2
   char   (*cunit)[72];		/* CUNITia keyvalues for each coord axis.   */
   char   (*ctype)[72];		/* CTYPEia keyvalues for each coord axis.   */
d1171 2
a1172 2
   double lonpole;		/* LONPOLEa keyvalue.                       */
   double latpole;		/* LATPOLEa keyvalue.                       */
d1174 2
a1175 2
   double restfrq;		/* RESTFRQa keyvalue.                       */
   double restwav;		/* RESTWAVa keyvalue.                       */
d1177 1
a1177 1
   int    npv;			/* Number of PVi_ma keywords, and the       */
d1179 1
a1179 1
   struct pvcard *pv;		/* PVi_ma keywords for each i and m.        */
d1181 1
a1181 1
   int    nps;			/* Number of PSi_ma keywords, and the       */
d1183 1
a1183 1
   struct pscard *ps;		/* PSi_ma keywords for each i and m.        */
d1185 1
a1185 1
   /* Alternative header keyvalues (see the prologue above).                */
d1193 1
a1193 1
   double *crota;		/* CROTAia keyvalues for each coord axis.   */
d1223 1
a1223 1
   /* Information derived from the FITS header keyvalues by wcsset().      */
@


4.2.1.8
log
@Put the auxiliary members of the wcsprm into alphabetic order.
Referenced the README file for an overview of the library.
@
text
@d30 1
a30 1
*   $Id: wcs.h,v 4.2.1.7 2007/08/02 04:29:03 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 the wcs* routines
*   ----------------------------
d831 1
d833 3
a835 2
*         The address of the first element of an array of char[72] containing
*         the coordinate axis names, CNAMEia.
d846 1
a846 6
*      char dateavg[72], dateobs[72]
*         The date of observation in ISO format, yyyy-mm-ddThh:mm:ss.
*         DATE-AVG refers to a representative mid-point of the observation and
*         DATE-OBS refers to the start of the observation unless otherwise
*         explained in the comment field of the DATE-OBS keyword.
*
d848 3
a850 13
*         The equinox associated with dynamical equatorial or ecliptic
*         coordinate systems, EQUINOXa (or EPOCH in older headers).
*
*      double mjdavg, mjdobs
*         Modified Julian Date (MJD = JD - 2400000.5), MJD-AVG and MJD-OBS,
*         corresponding to DATE-AVG and DATE-OBS.
*
*      double obsgeo[3]
*         Location of the observer in a standard terrestrial reference frame,
*         OBSGEO-X, OBSGEO-Y, OBSGEO-Z (in metres).
*
*      char radesys[72]
*         The equatorial or ecliptic coordinate system type, RADESYSa.
d866 9
a874 3
*      double velangle
*         The angle in degrees that should be used to decompose an observed
*         velocity into radial and transverse components.
d876 3
a878 4
*      char wcsname[72]
*         The name given to the coordinate representation WCSNAMEa.  This
*         variable accomodates the longest allowed string-valued FITS keyword,
*         being limited to 68 characters, plus the null-terminating character.
d1140 1
a1140 1
#define wtbarr wtbarr_s		/* See prologue above.                      */
d1166 1
a1166 1
   double *crpix;		/* CRPIXja keyvalues for each pixel axis.   */
d1202 1
a1202 1

d1206 1
a1206 2
   char   dateavg[72];
   char   dateobs[72];
a1207 4
   double mjdavg;
   double mjdobs;
   double obsgeo[3];
   char   radesys[72];
d1210 1
a1211 3
   double velangl;
   double velosys;
   char   wcsname[72];
d1213 5
d1226 1
a1226 1
   /* Information derived from the FITS header keyvalues by wcsset().       */
@


4.2.1.9
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: wcs.h,v 4.2.1.8 2007/08/08 08:59:46 cal103 Exp cal103 $
@


4.2.1.10
log
@Minor amendments to the prologue comments.
@
text
@d31 1
a31 1
    $Id: wcs.h,v 4.2.1.9 2007/12/03 05:02:17 cal103 Exp cal103 $
d856 1
a856 2
*         coordinate systems, EQUINOXa (or EPOCH in older headers).  Not
*         applicable to ICRS equatorial or ecliptic coordinates.
d883 1
a883 1
*      double velangl
@


4.1
log
@WCSLIB 4.1: major changes to implement -LOG and -TAB coordinate axes, and to
implement units conversions in wcsset(); -TAB required new members of the
wcsprm struct - ntab, tab, nwtb, wtb; also added dateavg to wcsprm; set
wcs_errmsg[0] to "success"; removed support for K&R C; moved prototypes for
vector helper functions from wcs.h; changed position of crval in the wcsprm
struct for alignment; use memset() to initialize variables an wcsini(),
default value of lonpole is UNDEFINED, latpole is +90.0 (were 999.0); report
values to an extra decimal place in wcsprt(), and report all memory
management members; overhauled wcsset() to support -LOG and -TAB, making it
more general and splitting some of its functionality into new helper
functions wcs_types(), which uses new member wcsprm.types, and wcs_units()
that does units conversions based on cunit; wcsset() recognizes AIPS
spectral types, via wcs_types() and spctyp(); wcsset() resets lonpole and
latpole to the values actually used, and null-fills all string members
(mainly to prevent gdb printing garbage); new utility function wcssptr()
translates the spectral axis in a wcsprm struct.
@
text
@d3 1
a3 1
*   WCSLIB 4.1 - an implementation of the FITS WCS standard.
d30 1
a30 1
*   $Id: wcs.h,v 4.0 2005/02/04 06:11:18 cal103 Exp cal103 $
d33 1
a33 1
*   WCSLIB 4.1 - C routines that implement the FITS World Coordinate System
d1083 4
a1086 4
#include <lin.h>
#include <cel.h>
#include <spc.h>
#include <tab.h>
@


4.0
log
@WCSLIB 4.0: changed from LGPL to GPL; revised the prologue comments, in
particular to emphasise that the nelem argument in wcsp2s() and wcss2p() must
equal or exceed naxis.
@
text
@d3 1
a3 1
*   WCSLIB 4.0 - an implementation of the FITS WCS standard.
d30 1
a30 1
*   $Id: wcs.h,v 3.6 2004/08/25 05:07:57 cal103 Exp cal103 $
d33 1
a33 1
*   WCSLIB 4.0 - C routines that implement the FITS World Coordinate System
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)
d44 1
a44 1
*      (paper III, in preparation)
d57 3
a59 3
*   Three service routines, wcsini(), wcssub(), and wcsfree() are provided to
*   manage the wcsprm struct and another, wcsprt(), to prints its contents.
*   See "Coordinate transformation parameters" below for an explanation of the
d64 1
a64 1
*   struct always needs to be set up by wcsset() but it need not be called
d69 2
a70 2
*   celestial, and spectral transformation routines described in lin.h, cel.h
*   and spc.h.
d76 3
d82 11
a92 4
*   wcsini() allocates memory for arrays in a wcsprm struct and sets all
*   members of the struct to default values.  Memory is allocated for up to
*   NPVMAX PVi_ma cards or NPSMAX PSi_ma cards per WCS representation.  These
*   may be changed via wcsnpv() and wcsnps() before wcsini() is called.
d95 9
a103 8
*      alloc    int      If true, allocate memory for the crpix, etc. arrays
*                        (see "Memory allocation and deallocation below").
*                        Otherwise, it is assumed that pointers to these
*                        arrays have been set by the caller except if they are
*                        null pointers in which case memory will be allocated
*                        for them regardless.  (In other words, setting alloc
*                        true saves having to initalize these pointers to
*                        zero.)
d127 3
a129 3
*   wcsnpv() and wcsnps() change the values of NPVMAX (default 64) and
*   NPSMAX (default 8).  These control the number of PVi_ma and PSi_ma cards
*   that wcsini() should allocate space for.
d153 4
d235 3
d268 3
a270 1
*   SIN projection.  It also recognizes GLS as a synonym for SFL.
d491 34
d577 4
a580 4
*       Stokes.  However, as extraction is done in the order specified by
*       axes[] a longitude axis (if present) would be extracted first (via
*       axes[0]) and not subsequently (via axes[3]).  Likewise for the
*       latitude and cubeface axes in this example.
d590 13
a602 9
*   supplied and others that are computed from them.  In practice, it is
*   expected that a FITS header parser would scan the FITS header until it
*   encountered the NAXIS (or WCSAXESa) card which must occur near the start
*   of the header before any of the WCS keywords.  It would then use wcsini()
*   to allocate memory for arrays in the wcsprm struct and set default
*   values.  Then as it read and identified each WCS header card it would
*   load the value into the relevant wcsprm array element.  Finally it would
*   invoke wcsset(), either directly or indirectly, to set the derived members
*   of the wcsprm struct.
d619 1
a619 1
*         Pointer to the first element of an array of double containing the
d623 1
a623 1
*         Pointer to the first element of the PCi_ja (pixel coordinate)
d642 1
a642 1
*         for which the storage order is
d649 1
a649 1
*         Pointer to the first element of an array of double containing the
d652 4
d657 1
a657 1
*         Pointer to the first element of an array of char[72] containing the
d661 14
a674 5
*         For celestial coordinates, CRVALia, CDELTia, and CDi_ja are measured
*         in degrees and CUNITia is not applicable.
*
*         For spectral coordinates, CUNITia is currently ignored and default
*         (SI) units are assumed.
d676 2
a677 2
*         For simple linear coordinate types CUNITia may be used to label
*         coordinate values.
d684 1
a684 1
*         Pointer to the first element of an array of char[72] containing the
a696 4
*      double *crval
*         Pointer to the first element of an array of double containing the
*         coordinate reference values, CRVALia.
*
d699 6
a704 1
*         and LATPOLEa (degrees).
d711 1
a711 1
*         Pointer to the first element of an array of length npvmax of pvcard
d726 3
d731 1
a731 1
*         Pointer to the first element of an array of length npsmax of pscard
d747 3
d807 1
a807 1
*      char alt[4];
d815 1
a815 1
*      int colnum;
d823 4
a826 4
*      char wcsname[72];
*      char (*cname)[72];
*         The name given to the coordinate representation WCSNAMEa, and a
*         pointer to the first element of an array of char[72] containing the
d833 2
a834 2
*      double *crder, *csyer;
*         Pointers to the first elements of arrays of double recording the
d838 2
a839 2
*      char radesys[72];
*      double equinox;
d844 2
a845 2
*      char specsys[72], ssysobs[72];
*      double velosys;
d853 2
a854 2
*      char ssyssrc[72];
*      double zsource;
d858 1
a858 1
*      double obsgeo[3];
d862 70
a931 9
*      char dateobs[72]
*         The date of observation in ISO format, yyyy-mm-ddThh:mm:ss.  It
*         refers to the start of the observation unless otherwise explained in
*         the comment field of the DATE-OBS card.
*
*      double mjdobs, mjdavg;
*         Modified Julian Date (MJD = JD - 2400000.5), MJD-OBS, corresponding
*         to DATE-OBS, and the MJD of a representative mid-point of the
*         observation, MJD-AVG.
d937 32
d973 1
a973 1
*      int lng, lat, spc
d981 1
a981 1
*         separate axis (see Note 1 above).
d995 2
a996 6
*      int m_flag, m_naxis
*      char (*m_cunit)[72], (*m_ctype)[72]
*      double *m_crpix, *m_pc, *m_cdelt, *m_crval
*      struct pvcard *m_pv
*      double *m_cd, *m_crota
*         These are used for memory management by wcsini() and wcsfree().
d1014 6
a1019 4
*   wcsini() allocates memory for the crpix, pc, cdelt, cunit, ctype, crval,
*   pv, ps, cd, crota, cname, crder, and csyer arrays in the wcsprm struct.
*   It is provided as a service routine; usage is optional, and the caller is
*   at liberty to set these pointers independently.
d1025 1
a1025 1
*   by wcsfree() which wcsini() uses to free any memory that it may have
d1028 2
a1029 2
*   the same wcsprm struct.  Likewise, wcsset() deallocates memory that it
*   may have allocated in the same wcsprm struct on a previous invokation.
d1031 6
a1036 6
*   However, a memory leak will result if a wcsprm struct goes out of scope
*   before the memory has been free'd, either by wcsfree() or otherwise.
*   Likewise, if the wcsprm struct itself has been malloc'd and the allocated
*   memory is not free'd when the memory for the struct is free'd.  A leak may
*   also arise if the caller interferes with the array pointers in the
*   "private" part of the wcsprm struct.
d1083 4
a1086 3
#include "lin.h"
#include "cel.h"
#include "spc.h"
d1111 1
a1111 1
                                /* Struct used for storing PVi_ma cards.    */
d1118 1
a1118 1
                                /* Struct used for storing PSi_ma cards.    */
d1125 16
d1153 1
a1157 1
   double *crval;		/* CRVALia cards for each coordinate axis.  */
d1197 1
d1201 8
d1211 1
d1213 1
a1213 1
   int    lng, lat, spec;	/* Longitude, latitude, and spectral axis   */
d1216 1
d1223 1
a1224 1
   double *m_crpix, *m_pc, *m_cdelt, *m_crval;
d1230 3
a1232 2

   int    padding1;		/* (Dummy inserted for alignment purposes.) */
a1241 1

a1242 1

a1243 1

a1244 1

a1245 1

a1247 1

a1249 1

d1252 1
a1252 4

int wcs_allEq(int, int, const double *);
void wcs_setAll(int, int, double *);
void wcs_setAli(int, int, int *);
@


3.6
log
@WCSLIB 3.6: added new service routine wcssub() and redefined wcscopy() as a
preprocessor macro that invokes it; removed vsource from the wcsprm struct and
added ssyssrc; "error status/code/number" is now referred to consistently as
the "status return value"; refer to wcsset() as doing setup rather than
initialization to distinguish it from wcsini(); 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: wcs.h,v 3.5 2004/06/28 04:09:39 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,
d49 8
d58 13
a70 10
*   manage the wcsprm struct (see "Memory allocation and deallocation" below).
*   Another, wcsprt(), prints its contents.  See "Coordinate transformation
*   parameters" below for an explanation of the anticipated usage of these
*   routines.
*
*   A setup routine, wcsset(), computes indices from the ctype array but need
*   not be called explicitly - see the explanation of wcs.flag below.
*
*   wcsp2s() and wcss2p() are high level driver routines for the WCS linear,
*   celestial, and spectral transformation routines.
d79 4
a82 6
*   wcsini() allocates memory for the crpix, pc, cdelt, cunit, ctype, crval,
*   pv, ps, cd, crota, cname, crder, and csyer arrays in the wcsprm struct and
*   sets all members of the wcsprm struct to default values.  Memory is
*   allocated for up to NPVMAX PVi_ma cards or NPSMAX PSi_ma cards per WCS
*   representation.  These may be changed via wcsnpv() and wcsnps() before
*   wcsini() is called.
d156 4
a159 3
*                        numbers to extract.  Order is significant; axes[0] is
*                        the axis number of the input image that corresponds
*                        to the first axis in the subimage, etc.
d232 1
a232 1
*   This service routine may be used to print the members of a wcsprm struct.
d246 1
a246 1
*   Sets up a wcsprm data structure according to information supplied within
d253 2
a254 2
*   wcsp2s() and wcss2p() if the "flag" structure member is anything other
*   than a predefined magic value.
d276 1
a276 1
*   Transform an array of pixel coordinates to world coordinates.
d285 3
d334 1
a334 1
*   Transform an array of world coordinates to pixel coordinates.
d343 3
d394 3
a396 3
*   Given either the celestial longitude or latitude plus an element of the
*   pixel coordinate solve for the remaining elements by iterating on the
*   unknown celestial coordinate element using wcss2p().
d500 2
a501 2
*       extracted in the same order as they occur the input image by combining
*       preprocessor codes, for example
d557 2
a558 2
*         Number of pixel and world coordinate elements, given by NAXIS or
*         WCSAXESa.
d836 2
a837 2
*   coordinate elements, naxis, stored in the wcsprm struct.  Exception: when
*   ncoord == 1, nelem is not used.
d841 2
a842 3
*   This was considered preferable to declaring them as simple
*   pointers-to-double which gives no indication that storage is associated
*   with them.
d1018 1
a1018 1
                                /* numbers.                                 */
d1025 1
a1025 1
   int m_flag, m_naxis;		/* The remainder are for memory management. */
d1033 1
@


3.5
log
@WCSLIB 3.5: new function wcsnpv() changes NPVMAX, no longer a C-preprocessor
macro but a global variable whose value is recorded in the wcsprm struct as
npvmax; handle PSi_ma cards similarly, and provide data members for all
auxiliary WCS header cards; fixed comments relating to altlin usage; added
the alternate version code to FITS WCS keywords mentioned in comments.
@
text
@d3 1
a3 1
*   WCSLIB 3.5 - an implementation of the FITS WCS convention.
d30 1
a30 1
*   $Id: wcs.h,v 3.4 2004/02/11 00:15:03 mcalabre Exp mcalabre $
d33 1
a33 1
*   WCSLIB 3.5 - C routines that implement the FITS World Coordinate System
d49 9
a64 14
*   An initialization routine, wcsset(), computes indices from the ctype
*   array but need not be called explicitly - see the explanation of
*   wcs.flag below.
*
*   Three service routines, wcsini(), wcscopy(), and wcsfree() are provided to
*   manage the wcsprm struct.  A third, wcsprt(), prints its contents.  See
*   "Coordinate transformation parameters" below for an explanation of the
*   anticipated usage of these routines.
*
*
*   Service routines for the wcsprm struct; wcsini(), wcscopy(), & wcsfree()
*   -----------------------------------------------------------------------
*   These service routines are provided to manage the wcsprm struct (see also
*   "Memory allocation and deallocation" below).
d66 2
a67 1
*
d69 5
a73 4
*   and pv arrays and sets the members of the wcsprm struct to default values.
*   Memory is allocated for up to NPVMAX PVi_ma cards or NPSMAX PSi_ma cards
*   per WCS representation.  These may be changed via wcsnpv() and wcsnps()
*   before wcsini() is called.
d76 9
a84 7
*      alloc    int      If true, allocate memory for the crpix, pc, cdelt,
*                        cunit, ctype, crval, and pv arrays.  Otherwise, it is
*                        assumed that pointers to these arrays have been set
*                        by the caller except if they are null pointers in
*                        which case memory will be allocated for them
*                        regardless.  (In other words, setting alloc true
*                        saves having to initalize these pointers to zero.)
d99 1
a99 1
*               int      Error status
d102 1
a102 1
*                           2: Memory allocation error.
d105 2
d118 14
a131 4
*   wcscopy() does a deep copy of one wcsprm struct to another, using wcsini()
*   to allocate memory for its arrays if required.  Only the "information to
*   be provided" part of the struct is copied; a call to wcsset() is required
*   to initialize the remainder.
d134 9
a142 8
*      alloc    int      If true, allocate memory for the crpix, pc, cdelt,
*                        cunit, ctype, crval, and pv arrays in the
*                        destination.  Otherwise, it is assumed that pointers
*                        to these arrays have been set by the caller except if
*                        they are null pointers in which case memory will be
*                        allocated for them regardless.
*      wcsfrom  const struct wcsprm*
*                        Struct to copy from.
d145 42
a186 4
*      wcsto    struct wcsprm*
*                        Struct to copy to.  wscto->flag should be set to -1
*                        if wcsto was not previously initialized (memory
*                        leaks may result if it was previously initialized).
d189 1
a189 1
*               int      Error status
d192 3
a194 1
*                           2: Memory allocation error.
d197 9
d215 1
a215 1
*               int      Error status
d229 1
a229 1
*               int      Error status
d234 4
a237 4
*   Initialization routine; wcsset()
*   --------------------------------
*   Initializes a wcsprm data structure according to information supplied
*   within it (see "Coordinate transformation parameters" below).
d251 1
a251 1
*               int      Error status
d254 1
a254 1
*                           2: Memory allocation error.
d299 1
a299 1
*                        Error status for each coordinate:
d304 1
a304 1
*               int      Error status
d307 1
a307 1
*                           2: Memory allocation error.
d354 1
d356 1
a356 1
*                        Error status for each coordinate:
d361 1
a361 1
*               int      Error status
d364 1
a364 1
*                           2: Memory allocation error.
d396 1
d405 1
d410 1
d440 1
a440 1
*               int      Error status
d443 1
a443 1
*                           2: Memory allocation error.
d483 33
d527 2
a528 2
*   invoke wcsset(), either directly or indirectly, to initialize the derived
*   members of the wcsprm struct.
d532 2
a533 2
*         of the wcsprm struct are set or modified.  This signals the
*         initialization routine, wcsset(), to recompute intermediaries.
d751 1
a751 1
*      double velosys, vsource, zsource;
d757 6
a762 3
*         coordinate, VELOSYSa, and the apparent radial velocity (m/s),
*         VSOURCEa, and redshift, ZSOURCEa, of the source with respect to the
*         observer.
d768 1
a768 1
*      char date-obs[72]
d832 4
a835 3
*   wcsini() allocates memory for the crpix, pc, and cdelt arrays in the
*   wcsprm struct.  It is provided as a service routine; usage is optional,
*   and the caller is at liberty to set these pointers independently.
d857 1
a857 1
*   unallocated memory.  Use wcscopy() instead to make a deep copy.
d860 3
a862 3
*   Error codes
*   -----------
*   Error messages to match the error codes returned from each function are
d907 6
a912 5
#if !defined(__STDC__) && !defined(__cplusplus)
#ifndef const
#define const
#endif
#endif
d917 1
d992 1
a992 1
   double vsource;
d1021 5
a1025 3
#if __STDC__ || defined(__cplusplus)
   int wcsnpv(int);
   int wcsnps(int);
d1027 1
a1027 1
   int wcsini(int, int, struct wcsprm *);
d1029 1
a1029 1
   int wcscopy(int, const struct wcsprm *, struct wcsprm *);
d1031 1
a1031 1
   int wcsfree(struct wcsprm *);
d1033 1
a1033 1
   int wcsprt(const struct wcsprm *);
d1035 1
a1035 1
   int wcsset(struct wcsprm *);
d1037 2
a1038 2
   int wcsp2s(struct wcsprm *, int, int, const double[],
              double[], double[], double[], double[], int[]);
d1040 2
a1041 2
   int wcss2p(struct wcsprm *, int, int, const double[],
              double[], double[], double[], double[], int[]);
d1043 2
a1044 2
   int wcsmix(struct wcsprm *, int, int, const double[], double, int,
              double[], double[], double[], double[], double[]);
d1046 5
a1050 10
   int wcs_allEq(int, int, const double *);
   void wcs_setAll(int, int, double *);
   void wcs_setAli(int, int, int *);
#else
   int wcsnpv(), wcsnps();
   int wcsini(), wcscopy(), wcsfree(), wcsprt(), wcsset(), wcsp2s(), wcss2p(),
       wcsmix();
   int wcs_allEq();
   void wcs_setAll(), wcs_setAli();
#endif
a1051 1
#define WCSLEN (sizeof(struct wcsprm)/sizeof(int))
@


3.4
log
@WCSLIB 3.4: incremented the date of Paper III; trivial change to wording in
prologue.
@
text
@d3 1
a3 1
*   WCSLIB 3.4 - an implementation of the FITS WCS convention.
d28 3
d33 1
a33 1
*   WCSLIB 3.4 - C routines that implement the FITS World Coordinate System
d71 2
a72 1
*   wcsini() allocates memory for the crpix, pc, cdelt, ctype, cunit, crval,
d74 3
a76 2
*   Memory is allocated for up to NPVMAX (default 64) PVi_m cards per WCS
*   representation.
d80 1
a80 1
*                        ctype, cunit, crval, and pv arrays.  Otherwise, it is
d85 1
a85 1
*                        saves having to initalize these pointers to zero.) 
d106 11
d124 1
a124 1
*                        ctype, cunit, crval, and pv arrays in the
d327 1
a327 2
*      mixcel   int      Which element of the celestial coordinate is
*                        given:
d424 6
a429 6
*   encountered the NAXIS (or WCSAXES) card which must occur near the start of
*   the header before any of the WCS keywords.  It would then use wcsini() to
*   allocate memory for arrays in the wcsprm struct and set default values.
*   Then as it read and identified each WCS header card it would load the
*   value into the relevant wcsprm array element.  Finally it would invoke
*   wcsset(), either directly or indirectly, to initialize the derived
d444 1
a444 1
*         WCSAXES.
d448 1
a448 1
*         coordinate reference pixel, CRPIXj.
d451 1
a451 1
*         Pointer to the first element of the PCi_j (pixel coordinate)
d478 1
a478 1
*         coordinate increments, CDELTi.
d480 1
a480 1
*      char (*ctype)[72]
d482 8
a489 1
*         coordinate axis types, CTYPEi.
d491 2
a492 5
*         The ctype[][72] keyword values must be in upper case and there must
*         be zero or one pair of matched celestial axis types, and zero or one
*         spectral axis.  The ctype[][72] strings should be padded with blanks
*         on the right and null-terminated so that they are at least eight
*         characters in length.
d498 1
a498 1
*      char (*cunit)[72]
d500 1
a500 2
*         CUNITi cards which define the units of measurement of the CRVALi,
*         CDELTi, and CDi_j cards.
d502 5
a506 2
*         For celestial coordinates, CRVALi, CDELTi, and CDi_j are measured in
*         degrees and CUNITi is not applicable.
a507 6
*         For spectral coordinates, CUNITi is currently ignored and default
*         (SI) units are assumed.
*
*         For simple linear coordinate types CUNITi may be used to label
*         coordinate values.
*
d514 1
a514 1
*         coordinate reference values, CRVALi.
d517 2
a518 2
*         The native longitude and latitude of the celestial pole, LONPOLE and
*         LATPOLE (degrees).
d523 1
a523 1
*      int npv
d525 2
a526 3
*         Pointer to the first element of an array of length npv of pvcard
*         structs.  As a FITS header parser encounters each PVi_m card it may
*         load it into a pvcard struct in the array:
d529 1
a529 1
*               int    i;		...Axis number, as in PVi_m,
d531 1
a531 1
*               int    m;		...Parameter number, as in PVi_m,
d536 21
a556 1
*         wcsset() interprets these as required.
d563 3
a565 3
*         associated with the CDi_j and CROTAi cards.  Although these may not
*         formally co-exist with PCi_j, the approach here is simply to ignore
*         them if given in conjunction with PCi_j.
d567 1
a567 1
*         altlin is a bit flag which denotes which of these cards are present
d570 1
a570 1
*         Bit 0: PCi_j is present.
d572 9
a580 9
*         Bit 1: CDi_j is present.  Matrix elements in the IRAF convention are
*                equivalent to the product CDi_j = CDELTi * PCi_j, but the
*                defaults differ from that of the PCi_j matrix.  If one or
*                more CDi_j cards are present then all unspecified CDi_j
*                default to zero.  If no CDi_j (or CROTAi) cards are present,
*                then the header is assumed to be in PCi_j form whether or not
*                any PCi_j cards are present since this results in an
*                interpretation of CDELTi consistent with the original FITS
*                specification.
d582 2
a583 2
*                While CDi_j may not formally co-exist with PCi_j, it may
*                co-exist with CDELTi and CROTAi which are to be ignored.
d585 1
a585 1
*         Bit 2: CROTAi is present.  In the AIPS convention, CROTAi may only
d588 2
a589 1
*                applied AFTER the CDELTi; any other CROTAi cards are ignored.
d591 2
a592 2
*                CROTAi may not formally co-exist with PCi_j.  CROTAi and
*                CDELTi may formally co-exist with CDi_j but if so are to be
d595 1
a595 1
*         CDi_j and CROTAi cards, if found, are to be stored in the cd and
d598 5
a602 5
*            Whenever a PCi_j  card is encountered: altlin &= 1;
*            Whenever a CDi_j  card is encountered: altlin &= 2;
*            Whenever a CROTAi card is encountered: altlin &= 4;
*         If none of these bits are set the PCi_j representation results, i.e.
*         pc and cdelt will be used as given.
d605 1
a605 1
*         are translated immediately to PCi_j by wcsset() and are nowhere
d607 69
a675 3
*         cdelt to unity if CDi_j is present (and no PCi_j).  If no CROTAi is
*         associated with the latitude axis, wcsset() reverts to a unity PCi_j
*         matrix.
d677 1
d688 1
a688 1
*         provided that the PCi_j matrix does not transpose axes.
d708 1
a708 1
*      char (*m_ctype)[72], (*m_cunit)[72]
a791 3
*
*   Author: Mark Calabretta, Australia Telescope National Facility
*   $Id: wcs.h,v 3.3 2003/10/21 08:51:00 mcalabre Exp mcalabre $
d822 1
a822 3
#define NPVMAX 64		/* Maximum number of PVi_m cards.           */

                                /* Struct used for storing PVi_m cards.     */
d824 2
a825 2
   int    i;			/* Axis number, as in PVi_m (1-relative).   */
   int    m;			/* Parameter number, ditto  (0-relative).   */
d829 7
d845 21
a865 16
   double *crpix;		/* CRPIXj cards for each pixel axis.        */
   double *pc;			/* PCi_j  linear transformation matrix.     */
   double *cdelt;		/* CDELTi cards for each coordinate axis.   */

   char   (*ctype)[72];		/* CTYPEi cards for each coordinate axis.   */
   char   (*cunit)[72];		/* CUNITi cards for each coordinate axis.   */

   double *crval;		/* CRVALi cards for each coordinate axis.   */
   double lonpole;		/* LONPOLE card.                            */
   double latpole;		/* LATPOLE card.                            */

   double restfrq;		/* RESTFRQ card.                            */
   double restwav;		/* RESTWAV card.                            */

   int    npv;			/* Total number of PVi_m cards.             */
   struct pvcard *pv;		/* PVi_m cards for each i and m.            */
d870 24
a893 5
				/*   Bit 0: PCi_j  is present,              */
				/*   Bit 1: CDi_j  is present,              */
				/*   Bit 2: CROTAi is present.              */
   double *cd;			/* CDi_j linear transformation matrix.      */
   double *crota;		/* CROTAi cards for each coordinate axis.   */
a900 1
   int    padding1;		/* (Dummy inserted for alignment purposes.) */
d907 1
a907 1
   char  (*m_ctype)[72], (*m_cunit)[72];
d910 1
d912 3
a914 1
   int    padding2;		/* (Dummy inserted for alignment purposes.) */
d918 3
d944 1
@


3.3
log
@WCSLIB 3.3
@
text
@d3 2
a4 2
*   WCSLIB 3.3 - an implementation of the FITS WCS convention.
*   Copyright (C) 1995-2003, Mark Calabretta
d30 1
a30 1
*   WCSLIB 3.3 - C routines that implement the FITS World Coordinate System
d40 1
a40 1
*      Greisen, E.W., Valdes, F.G., Calabretta, M.R., & Allen, S.L. 2003, A&A,
d556 2
a557 2
*                CROTAi may not formally co-exist with PCi_j.  It CROTAi (and
*                CDELTi) may formally co-exist with CDi_j but if so is to be
d692 1
a692 1
*   $Id: wcs.h,v 3.2 2003/09/09 04:37:19 mcalabre Exp mcalabre $
@


3.2
log
@WCSLIB 3.2: renamed wcscpy() to wcscopy() to avoid a conflict with the POSIX
"wide character string" function of the same name (wchar.h); augmented the
usage notes for wcsini() and wcscopy() to document the option to initialize
memory management by setting wcsprm.flag == -1; rationalized function return
codes and messages.
@
text
@d3 1
a3 1
*   WCSLIB 3.2 - an implementation of the FITS WCS convention.
d30 1
a30 1
*   WCSLIB 3.2 - C routines that implement the FITS World Coordinate System
d692 1
a692 1
*   $Id: wcs.h,v 3.1 2003/04/28 03:50:41 mcalabre Exp mcalabre $
@


3.1
log
@WCSLIB 3.1
Added support for CUNITi cards to wcsprm (but not currently implemented);
added macro definition of WCSLEN.
@
text
@d3 1
a3 1
*   WCSLIB 3.1 - an implementation of the FITS WCS convention.
d30 1
a30 1
*   WCSLIB 3.1 - C routines that implement the FITS World Coordinate System
d57 1
a57 1
*   Three service routines, wcsini(), wcscpy(), and wcsfree() are provided to
d63 1
a63 1
*   Service routines for the wcsprm struct; wcsini(), wcscpy(), & wcsfree()
d79 2
a80 1
*                        regardless.
d86 1
a86 1
*   Returned:
d89 4
d97 2
a98 1
*                           1: Memory allocation error.
d101 1
a101 1
*   wcscpy() does a deep copy of one wcsprm struct to another, using wcsini()
d116 1
a116 1
*   Returned:
d118 3
a120 1
*                        Struct to copy to.
d125 2
a126 1
*                           1: Memory allocation error.
d140 1
d154 1
d176 4
a179 3
*                           1: Memory allocation error.
*                           2: Singular linear transformation matrix.
*                           3: Inconsistent or unrecognized coordinate axis
d181 3
a183 3
*                           4: Invalid parameter value.
*                           5: Invalid coordinate transformation parameters.
*                           6: Ill-conditioned coordinate transformation
d229 4
a232 3
*                           1: Memory allocation error.
*                           2: Singular linear transformation matrix.
*                           3: Inconsistent or unrecognized coordinate axis
d234 3
a236 3
*                           4: Invalid parameter value.
*                           5: Invalid coordinate transformation parameters.
*                           6: Ill-conditioned coordinate transformation
d238 2
a239 1
*                           7: Invalid pixel coordinate.
d285 4
a288 3
*                           1: Memory allocation error.
*                           2: Singular linear transformation matrix.
*                           3: Inconsistent or unrecognized coordinate axis
d290 3
a292 3
*                           4: Invalid parameter value.
*                           5: Invalid coordinate transformation parameters.
*                           6: Ill-conditioned coordinate transformation
d294 2
a295 1
*                           7: Invalid world coordinate.
d362 4
a365 3
*                           1: Memory allocation error.
*                           2: Singular linear transformation matrix.
*                           3: Inconsistent or unrecognized coordinate axis
d367 3
a369 3
*                           4: Invalid parameter value.
*                           5: Invalid coordinate transformation parameters.
*                           6: Ill-conditioned coordinate transformation
d371 2
a372 2
*                           7: Invalid world coordinate.
*                           8: No solution found in the specified interval.
d419 7
a425 2
*         are set or modified.  This signals the initialization routine,
*         wcsset(), to recompute intermediaries.
d653 1
a653 1
*   unallocated memory.  Use wcscpy() instead to make a deep copy.
d658 2
a659 4
*   Error messages to match the error codes for wcsini(), wcscpy(), wcsset(),
*   wcsp2s(), wcss2p(), and wcsmix() are encoded in the wcsini_errmsg,
*   wcscpy_errmsg, wcsset_errmsg, wcsp2s_errmsg, and wcss2p_errmsg character
*   arrays.
d692 1
a692 1
*   $Id: wcs.h,v 3.0 2003/04/01 04:10:53 mcalabre Exp mcalabre $
d713 9
a721 6
extern const char *wcsini_errmsg[];
extern const char *wcscpy_errmsg[];
extern const char *wcsset_errmsg[];
extern const char *wcsp2s_errmsg[];
extern const char *wcss2p_errmsg[];
extern const char *wcsmix_errmsg[];
d790 1
a790 1
   int wcscpy(int, const struct wcsprm *, struct wcsprm *);
d811 1
a811 1
   int wcsini(), wcscpy(), wcsfree(), wcsprt(), wcsset(), wcsp2s(), wcss2p(),
@


3.0
log
@WCSLIB 3.0
@
text
@d3 1
a3 1
*   WCSLIB 3.0 - an implementation of the FITS WCS convention.
d30 1
a30 1
*   WCSLIB 3.0 - C routines that implement the FITS World Coordinate System
a37 1
*      "Representations of spectral coordinates in FITS",
d68 2
a69 2
*   wcsini() allocates memory for the crpix, pc, cdelt, ctype, crval, and pv
*   arrays and sets the members of the wcsprm struct to default values.
d75 1
a75 1
*                        ctype, crval, and pv arrays.  Otherwise, it is
d102 5
a106 5
*                        ctype, crval, and pv arrays in the destination.
*                        Otherwise, it is assumed that pointers to these
*                        arrays have been set by the caller except if they are
*                        null pointers in which case memory will be allocated
*                        for them regardless.
d457 18
d584 1
a584 1
*      char (*m_ctype)[72]
d672 1
a672 1
*   $Id: wcs.h,v 2.8 2001/11/15 03:29:43 mcalabre Exp $
a713 1
   int    padding1;		/* (Dummy inserted for alignment purposes.) */
d723 1
d750 1
a750 1
   int    padding2;		/* (Dummy inserted for alignment purposes.) */
d757 1
a757 1
   char  (*m_ctype)[72];
d761 1
d793 2
@


2.9
log
@Updated date in copyright notice.
@
text
@d1 1
a1 1
/*=============================================================================
d3 2
a4 2
*   WCSLIB - an implementation of the FITS WCS proposal.
*   Copyright (C) 1995-2002, Mark Calabretta
d22 4
a25 4
*      Postal address: Dr. Mark Calabretta,
*                      Australia Telescope National Facility,
*                      P.O. Box 76,
*                      Epping, NSW, 2121,
d28 626
d655 1
a655 1
*   $Id: wcs.h,v 2.8 2001/11/15 03:29:43 mcalabre Exp mcalabre $
d661 1
d663 1
a663 1
#include "lin.h"
d669 24
d694 50
a743 5
   int flag;
   char pcode[4];
   char lngtyp[5], lattyp[5];
   int lng, lat;
   int cubeface;
d747 5
a751 44
   int wcsset(const int,
              const char[][9],
              struct wcsprm *);

   int wcsfwd(const char[][9],
              struct wcsprm *,
              const double[],
              const double[],
              struct celprm *,
              double *,
              double *,
              struct prjprm *,
              double[],
              struct linprm *,
              double[]);

   int wcsrev(const char[][9],
              struct wcsprm *,
              const double[],
              struct linprm *,
              double[],
              struct prjprm *,
              double *,
              double *,
              const double[],
              struct celprm *,
              double[]);

   int wcsmix(const char[][9],
              struct wcsprm *,
              const int,
              const int,
              const double[],
              const double,
              int,
              double[],
              const double[],
              struct celprm *,
              double *,
              double *,
              struct prjprm *,
              double[],
              struct linprm *,
              double[]);
d753 16
d770 4
a773 1
   int wcsset(), wcsfwd(), wcsrev(), wcsmix();
a774 7

extern const char *wcsset_errmsg[];
extern const char *wcsfwd_errmsg[];
extern const char *wcsrev_errmsg[];
extern const char *wcsmix_errmsg[];

#define WCSSET 137
@


2.8
log
@Changed date in copyright notice.
@
text
@d4 1
a4 1
*   Copyright (C) 1995-2001, Mark Calabretta
d29 1
a29 1
*   $Id: wcs.h,v 2.7 2000/05/10 04:44:05 mcalabre Exp mcalabre $
@


2.7
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
*   Copyright (C) 1995-2000, Mark Calabretta
d29 1
a29 1
*   $Id: wcs.h,v 2.6 1999/05/26 01:32:18 mcalabre Exp mcalabre $
d59 2
a60 1
              struct celprm *, 
d62 2
a63 3
              double *, 
              struct prjprm *, 
              double[], 
d69 1
a69 1
              const double[], 
d71 3
a73 2
              double[], 
              struct prjprm *, 
d75 2
a76 3
              double *, 
              const double[], 
              struct celprm *, 
d92 1
a92 1
              double[], 
@


2.6
log
@Added RCS id.
@
text
@d4 1
a4 1
*   Copyright (C) 1995-1999, Mark Calabretta
d29 1
a29 1
*   $Id$
@


2.5
log
@Added copyright notice; prefixed include guard names with "WCSLIB_".
@
text
@d28 2
@


2.4
log
@Include cel.h and lin.h earlier to avoid nested "extern C {...}".
@
text
@d1 28
a28 2
#ifndef WCS
#define WCS
d30 3
d109 1
a109 1
#endif /* WCS */
@


2.3
log
@Fixed declaration of ctype arguments in wcsrev() and wcsmix() - found by
gcc.
@
text
@d4 3
a9 3

#include "cel.h"
#include "lin.h"
@


2.2
log
@Added const-correctness to function arguments.
Implemented the CUBEFACE axis for quadcube projections.
Adapted to C++ usage.
Added external arrays of error messages indexed by function return value.
@
text
@d36 1
a36 1
   int wcsrev(char[][9],
d48 1
a48 1
   int wcsmix(char[][9],
@


2.1
log
@Added definition of the wcsprm struct, function prototype for wcsset(),
and revised function prototypes for wcsfwd(), wcsrev(), and wcsmix().
@
text
@d4 4
d16 1
d19 3
a21 3
#if __STDC__
   int wcsset(int,
              char[][9],
d24 1
a24 1
   int wcsfwd(char[][9],
d26 2
a27 2
              double[],
              double[],
d38 1
a38 1
              double[], 
d44 1
a44 1
              double[], 
d50 4
a53 1
              int,
d56 1
a56 4
              double,
              int,
              double[],
              double[],
d65 1
a65 1
#else /* not __STDC__ */
d67 1
a67 1
#endif /* __STDC__ */
d69 5
d75 4
@


2.0
log
@WCSLIB 2.0
@
text
@d7 7
d15 8
a22 2
   int wcsfwd(char *,
              double, double,
d24 2
a25 1
              double *, double *, 
d31 2
a32 1
   int wcsrev(char *,
d37 3
a39 1
              double *, double *, 
d41 1
a41 1
              double *, double *);
d43 2
a44 1
   int wcsmix(char *,
d46 6
a51 2
              double *, double, int,
              double *, double *,
d53 2
a54 1
              double *, double *,
d61 1
a61 1
   int wcsfwd(), wcsrev(), wcsmix();
d63 2
@


1.2
log
@New high level driver routines, the older drivers were renamed to celset(),
celfwd(), and celrev() (in cel.c).
@
text
@@


1.1
log
@Initial revision
@
text
@d4 2
a5 1
#include "proj.h"
d7 18
a24 4
struct wcsprm {
   int flag;
   double ref[3];
   double euler[6];
d26 10
a35 8
#if __STDC__
   int (*prjfwd)(double, double, struct prjprm *, double *, double *);
   int (*prjrev)(double, double, struct prjprm *, double *, double *);
#else
   int (*prjfwd)();
   int (*prjrev)();
#endif
};
d37 3
a39 1
#define WCSSET 137
@
