1; -----------------------------------------------------------------------------
2;
3;  Copyright (C) 1997-2013  Krzysztof M. Gorski, Eric Hivon, Anthony J. Banday
4;
5;
6;
7;
8;
9;  This file is part of HEALPix.
10;
11;  HEALPix is free software; you can redistribute it and/or modify
12;  it under the terms of the GNU General Public License as published by
13;  the Free Software Foundation; either version 2 of the License, or
14;  (at your option) any later version.
15;
16;  HEALPix is distributed in the hope that it will be useful,
17;  but WITHOUT ANY WARRANTY; without even the implied warranty of
18;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19;  GNU General Public License for more details.
20;
21;  You should have received a copy of the GNU General Public License
22;  along with HEALPix; if not, write to the Free Software
23;  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
24;
25;  For more information about HEALPix see http://healpix.sourceforge.net
26;
27; -----------------------------------------------------------------------------
28function reorder, map_in, in=in, out= out, n2r= n2r, r2n=r2n, help=help
29;+
30; NAME:
31;   reorder
32;
33; PURPOSE:
34;   change the ordering of a full sky Healpix map from Nested/Ring to
35;   Ring/Nested
36; CATEGORY:
37;   Healpix pixel toolkit
38;
39; CALLING SEQUENCE:
40;   map_out = reorder(map_in, [in=in, out=out, /n2r, /r2n, /help])
41;
42; INPUTS:
43;   map_in : a full sky Healpix map, can be of any type
44;  (float, integer, double) and any dimension
45;
46; OPTIONAL INPUTS:
47;   none
48;
49; KEYWORD PARAMETERS:
50;   help- if set, print out this Help header and exits
51;   in- is either 'RING' or 'NESTED' : input map ordering
52;   out- is either 'RING' or 'NESTED' : output map ordering
53;   r2n- if set, equivalent to in='RING', out='NESTED'
54;   n2r- if set, equivalent to in='NESTED', out='RING'
55;
56; OUTPUTS:
57;   map_out : a reordered full sky Healpix map,
58;   same size and same type of map_in
59;
60; OPTIONAL OUTPUTS:
61;   none
62;
63; COMMON BLOCKS:
64;   none
65;
66; SIDE EFFECTS:
67;   none
68;
69; RESTRICTIONS:
70;   none
71;
72; PROCEDURE:
73;
74; EXAMPLES:
75;   map_nest = reorder(map_ring,in='ring',out='nest')
76;   map_nest = reorder(map_ring,/r2n)
77;
78; MODIFICATION HISTORY:
79;    April 1999, EH, Caltech
80;    Jan   2000, EH,  improved documentation header
81;    Oct   2004, EH,  added extra dimension, added R2N  and N2R
82;    Mars  2012, EH, IAP: added HELP keyword
83;    May   2017, EH, IAP: replaced obsolete DATATYPE() with IDL's SIZE(/TYPE)
84;-
85
86 ok = (defined(in) && defined(out)) + keyword_set(r2n) + keyword_set(n2r)
87 if keyword_set(help) then begin
88     doc_library,'reorder'
89     return,-1
90 endif
91
92 if (N_params() ne 1) then begin
93     print,' map_out = reorder(map_in, [In=in, Out=out,] [/R2N, /N2R], [/HELP])'
94     return,0
95 endif
96
97 if (ok ne 1) then begin
98     message,/info,'should be either /R2N *or* /N2R *or* (IN=order_in, OUT=order_out)'
99     message,'Abort'
100 endif
101
102 if (defined(in)) then begin
103     kin  = strmid(strupcase(strtrim(in ,2)),0,4)
104     kout = strmid(strupcase(strtrim(out,2)),0,4)
105 endif
106 if (keyword_set(r2n)) then begin
107     kin = 'RING' & kout = 'NEST'
108 endif
109 if (keyword_set(n2r)) then begin
110     kout = 'RING' & kin = 'NEST'
111 endif
112
113
114 if (kin ne 'RING' and kin ne 'NEST') then begin
115     print,' In has to be either ''RING'' or ''NESTED'' '
116     print,' map_out = reorder(map_in, In=in, Out=out)'
117     return,0
118 endif
119
120 if (kout ne 'RING' and kout ne 'NEST') then begin
121     print,' Out has to be either ''RING'' or ''NESTED'' '
122     print,' map_out = reorder(map_in, In=in, Out=out)'
123     return,0
124 endif
125
126 if (kin eq kout) then return, map_in
127
128 np   = n_elements(map_in[*,0])
129 ncol = n_elements(map_in[0,*])
130 nside = npix2nside(np,err=err)
131
132 if (err ne 0) then begin
133     print,' map_in should be a full sky Healpix map'
134     print,' pixel #  = ',np
135     return,0
136 endif
137
138 npf = np/12
139 map_out = make_array(np, ncol, type=size(/type,map_in))
140 if (kin eq 'RING') then begin  ; ring -> nest
141     for j=0L, 11 do begin
142         ipn = lindgen(npf) + j*npf
143         nest2ring, nside, ipn, ipr
144         for ic=0,ncol-1 do map_out[ipn,ic] = map_in[ipr,ic]
145     endfor
146 endif
147 if (kin eq 'NEST') then begin  ; nest -> ring
148     for j=0L, 11 do begin
149         ipn = lindgen(npf) + j*npf
150         nest2ring, nside, ipn, ipr
151         for ic=0,ncol-1 do map_out[ipr,ic] = map_in[ipn,ic]
152     endfor
153 endif
154
155
156return, map_out
157end
158
159