askap-patchwork 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
patchwork/resample.py ADDED
@@ -0,0 +1,267 @@
1
+ """Resampling inputs onto the output frame with separable interpolation kernels"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import importlib.util
6
+ import os
7
+ import sys
8
+ from typing import TYPE_CHECKING, Literal
9
+
10
+ import numpy as np
11
+
12
+ if TYPE_CHECKING:
13
+ from numpy.typing import NDArray
14
+
15
+ from patchwork.io import Slices
16
+
17
+ Kernel = Literal["nearest", "linear", "cubic", "lanczos2", "lanczos3", "lanczos4"]
18
+ Backend = Literal["auto", "numpy", "numba", "fused"]
19
+
20
+
21
+ def kernel_width(kernel: Kernel) -> int:
22
+ """The number of taps of a kernel along each axis."""
23
+ if kernel.startswith("lanczos"):
24
+ return 2 * int(kernel[-1])
25
+ return {"nearest": 1, "linear": 2, "cubic": 4}[kernel]
26
+
27
+
28
+ def resolve_backend(backend: Backend) -> Literal["numpy", "numba", "fused"]:
29
+ """The backend that is used: the one asked for or, with ``auto``, numba when it is installed and numpy when not."""
30
+ has_numba = importlib.util.find_spec("numba") is not None
31
+ if backend == "auto":
32
+ return "numba" if has_numba else "numpy"
33
+ if backend != "numpy" and not has_numba:
34
+ msg = f"The {backend} backend needs numba, which is installed with `pip install askap-patchwork[numba]`"
35
+ raise ImportError(msg)
36
+ return backend
37
+
38
+
39
+ def available_cpus() -> int:
40
+ """The CPUs this process may run on: those a job scheduler such as SLURM has given it, where the system can say, and otherwise all of the machine's."""
41
+ affinity = getattr(os, "sched_getaffinity", None)
42
+ count = len(affinity(0)) if affinity is not None else os.cpu_count()
43
+ return max(count or 1, 1)
44
+
45
+
46
+ def _worker_threads() -> int:
47
+ """The threads of the dask worker this is a task of, which run that many tasks at once, or 1 outside a dask worker."""
48
+ # A task of a dask worker has distributed imported, so it is not imported here
49
+ distributed = sys.modules.get("distributed")
50
+ if distributed is None:
51
+ return 1
52
+ try:
53
+ return max(int(distributed.get_worker().state.nthreads), 1)
54
+ except ValueError:
55
+ return 1
56
+
57
+
58
+ def tile_threads(requested: int) -> int:
59
+ """The threads a task uses: the fused backend makes a tile with them, and every backend measures the noise of an image with them.
60
+
61
+ With 0, every CPU the process may run on (``available_cpus``) is shared
62
+ between the tiles it makes at once. A dask worker makes as many as it has
63
+ threads, so one with a single thread and 32 CPUs makes each tile with 32
64
+ threads, and one with a thread for each CPU makes each tile with 1.
65
+ ``patchwork.mosaic.mosaic`` shares the CPUs between its own
66
+ ``max_workers`` before any tile is made.
67
+
68
+ Worker processes that share the CPUs of one job cannot see each other, so
69
+ there each would use them all: give the number of threads instead.
70
+
71
+ Args:
72
+ requested (int): The threads asked for, ``ResampleOptions.tile_threads``, where 0 is as many as there are CPUs to use
73
+
74
+ Raises:
75
+ ValueError: Raised if a negative number is asked for
76
+
77
+ Returns:
78
+ int: The number of threads, which is at least 1
79
+ """
80
+ if requested < 0:
81
+ msg = f"tile_threads is {requested}, but must be 0 or more"
82
+ raise ValueError(msg)
83
+ return max(1, requested or available_cpus() // _worker_threads())
84
+
85
+
86
+ def _keys_cubic(distance: NDArray[np.float64]) -> NDArray[np.float64]:
87
+ """The Keys cubic convolution kernel with a = -0.5."""
88
+ t = np.abs(distance)
89
+ near = (1.5 * t - 2.5) * t**2 + 1
90
+ far = ((-0.5 * t + 2.5) * t - 4) * t + 2
91
+ return np.where(t <= 1, near, np.where(t < 2, far, 0.0))
92
+
93
+
94
+ def kernel_taps(
95
+ position: NDArray[np.float64], kernel: Kernel
96
+ ) -> tuple[NDArray[np.int64], NDArray[np.float64]]:
97
+ """The pixel indices and weights of the taps that interpolate each position.
98
+
99
+ Positions are zero-based pixel coordinates along one axis, with pixel centres
100
+ at integers. Both outputs have a trailing axis over the taps, and the weights
101
+ of each position sum to 1.
102
+
103
+ Args:
104
+ position (NDArray[np.float64]): Positions to interpolate at
105
+ kernel (Kernel): The interpolation kernel
106
+
107
+ Returns:
108
+ tuple[NDArray[np.int64], NDArray[np.float64]]: Index and weight of each tap
109
+ """
110
+ if kernel == "nearest":
111
+ index = np.floor(position + 0.5).astype(np.int64)[..., None]
112
+ return index, np.ones(index.shape)
113
+
114
+ width = kernel_width(kernel)
115
+ base = np.floor(position)
116
+ offsets = np.arange(width) - (width // 2 - 1)
117
+ index = base[..., None].astype(np.int64) + offsets
118
+ distance = (position - base)[..., None] - offsets
119
+
120
+ if kernel == "linear":
121
+ weights = np.clip(1 - np.abs(distance), 0.0, None)
122
+ elif kernel == "cubic":
123
+ weights = _keys_cubic(distance)
124
+ else:
125
+ a = width // 2
126
+ weights = np.sinc(distance) * np.sinc(distance / a)
127
+ weights /= np.sum(weights, axis=-1, keepdims=True)
128
+
129
+ return index, weights
130
+
131
+
132
+ def interpolate(
133
+ window: NDArray[np.floating],
134
+ x: NDArray[np.float64],
135
+ y: NDArray[np.float64],
136
+ kernel: Kernel,
137
+ backend: Backend = "numpy",
138
+ ) -> tuple[NDArray[np.float64], NDArray[np.bool]]:
139
+ """Interpolate an image at pixel positions with a separable kernel.
140
+
141
+ A position is invalid when any tap that carries weight falls on a
142
+ NaN or off the image, so blanked pixels grow by the kernel half-width rather
143
+ than biasing their neighbours.
144
+
145
+ Args:
146
+ window (NDArray[np.floating]): The (y, x) image, possibly a region of a larger one
147
+ x (NDArray[np.float64]): Zero-based x position in the window of each output pixel
148
+ y (NDArray[np.float64]): Zero-based y position in the window of each output pixel
149
+ kernel (Kernel): The interpolation kernel
150
+ backend (Backend, optional): Interpolate with numpy or with numba. Defaults to "numpy".
151
+
152
+ Returns:
153
+ tuple[NDArray[np.float64], NDArray[np.bool]]: The interpolated values (0 where invalid), and which are valid
154
+ """
155
+ values, valid = interpolate_stack(window[None], x, y, kernel, backend)
156
+ return values[0], valid[0]
157
+
158
+
159
+ def interpolate_stack(
160
+ windows: NDArray[np.floating],
161
+ x: NDArray[np.float64],
162
+ y: NDArray[np.float64],
163
+ kernel: Kernel,
164
+ backend: Backend = "numpy",
165
+ ) -> tuple[NDArray[np.float64], NDArray[np.bool]]:
166
+ """Interpolate a stack of images that share a grid, such as the channels of a cube, at pixel positions.
167
+
168
+ The taps are found once for every position and used for every image, as
169
+ ``interpolate`` would use them for each image alone.
170
+
171
+ Args:
172
+ windows (NDArray[np.floating]): The (image, y, x) stack, possibly a region of a larger one
173
+ x (NDArray[np.float64]): Zero-based x position in the window of each output pixel
174
+ y (NDArray[np.float64]): Zero-based y position in the window of each output pixel
175
+ kernel (Kernel): The interpolation kernel
176
+ backend (Backend, optional): Interpolate with numpy or with numba. Defaults to "numpy".
177
+
178
+ Returns:
179
+ tuple[NDArray[np.float64], NDArray[np.bool]]: The interpolated values (0 where invalid) and which are valid, both shaped ``(image, *x.shape)``
180
+ """
181
+ if resolve_backend(backend) != "numpy":
182
+ from patchwork import numba_kernels # noqa: PLC0415
183
+
184
+ code = {"nearest": 0, "linear": 1, "cubic": 2}.get(kernel, 3)
185
+ dtype = (
186
+ windows.dtype if windows.dtype in (np.float32, np.float64) else np.float64
187
+ )
188
+ values, valid = numba_kernels.interpolate_stack(
189
+ # Each pixel's taps then read every image from one place in memory
190
+ np.ascontiguousarray(np.moveaxis(windows, 0, -1), dtype=dtype),
191
+ np.ascontiguousarray(x, dtype=np.float64),
192
+ np.ascontiguousarray(y, dtype=np.float64),
193
+ code,
194
+ kernel_width(kernel),
195
+ )
196
+ return (
197
+ np.moveaxis(np.asarray(values, dtype=np.float64), -1, 0),
198
+ np.moveaxis(np.asarray(valid, dtype=bool), -1, 0),
199
+ )
200
+
201
+ n_images, ny, nx = windows.shape
202
+ finite_position = np.isfinite(x) & np.isfinite(y)
203
+ x_index, x_weights = kernel_taps(np.where(finite_position, x, 0.0), kernel)
204
+ y_index, y_weights = kernel_taps(np.where(finite_position, y, 0.0), kernel)
205
+
206
+ blank = ~np.isfinite(windows)
207
+ has_blank = bool(np.any(blank))
208
+ flat = np.reshape(
209
+ np.where(blank, 0.0, windows) if has_blank else windows, (n_images, -1)
210
+ )
211
+ flat_blank = np.reshape(blank, (n_images, -1))
212
+ # Taps that land off the window only need clipping where some of them do
213
+ clip_x = bool(np.min(x_index) < 0 or np.max(x_index) >= nx)
214
+ clip_y = bool(np.min(y_index) < 0 or np.max(y_index) >= ny)
215
+
216
+ values = np.zeros((n_images, *x.shape))
217
+ invalid = np.broadcast_to(~finite_position, values.shape).copy()
218
+ for j in range(y_index.shape[-1]):
219
+ row = y_index[..., j]
220
+ row_outside = (row < 0) | (row >= ny) if clip_y else None
221
+ row_start = (np.clip(row, 0, ny - 1) if clip_y else row) * nx
222
+ for i in range(x_index.shape[-1]):
223
+ column = x_index[..., i]
224
+ outside = row_outside
225
+ if clip_x:
226
+ column_outside = (column < 0) | (column >= nx)
227
+ outside = (
228
+ column_outside if outside is None else outside | column_outside
229
+ )
230
+ column = np.clip(column, 0, nx - 1)
231
+ index = row_start + column
232
+
233
+ tap_weight = y_weights[..., j] * x_weights[..., i]
234
+ if outside is not None or has_blank:
235
+ bad = (
236
+ flat_blank[:, index]
237
+ if has_blank
238
+ else np.zeros(values.shape, dtype=bool)
239
+ )
240
+ if outside is not None:
241
+ bad |= outside
242
+ invalid |= bad & (np.abs(tap_weight) > 1e-9)
243
+ values += tap_weight * flat[:, index]
244
+
245
+ return np.where(invalid, 0.0, values), ~invalid
246
+
247
+
248
+ def input_region(
249
+ shape: tuple[int, int],
250
+ x: NDArray[np.float64],
251
+ y: NDArray[np.float64],
252
+ kernel: Kernel,
253
+ ) -> Slices | None:
254
+ """The (y, x) region of an input that interpolating at the positions reads, or None if it reads none of it."""
255
+ finite = np.isfinite(x) & np.isfinite(y)
256
+ if not np.any(finite):
257
+ return None
258
+
259
+ margin = kernel_width(kernel) // 2 + 1
260
+ ny, nx = shape
261
+ x_low = max(int(np.floor(np.min(x[finite]))) - margin, 0)
262
+ x_high = min(int(np.ceil(np.max(x[finite]))) + margin, nx - 1)
263
+ y_low = max(int(np.floor(np.min(y[finite]))) - margin, 0)
264
+ y_high = min(int(np.ceil(np.max(y[finite]))) + margin, ny - 1)
265
+ if x_low > x_high or y_low > y_high:
266
+ return None
267
+ return slice(y_low, y_high + 1), slice(x_low, x_high + 1)
patchwork/rotate.py ADDED
@@ -0,0 +1,319 @@
1
+ """Rotate the Q and U of images or cubes from the frame they were imaged in to north at each pixel.
2
+
3
+ An interferometric image references the polarisation angle of every pixel to
4
+ one direction: north at its phase centre or, for ASKAP, at the boresight of the
5
+ observation, carried across the field as a fixed direction of the feeds.
6
+ ``patchwork mosaic`` turns each input into the frame of the mosaic as it
7
+ resamples it. This command does the same turn on an input's own grid, writing a
8
+ new image beside it whose Q and U are referenced to north at each pixel, the IAU
9
+ convention, with POLFRAME keywords that say so. A mosaic of rotated images then
10
+ needs no frame options, and differs from one rotated in flight only by the
11
+ rounding of float32.
12
+
13
+ The angle is the same for every channel of a pixel, so each block of rows is
14
+ rotated across every channel at once, in threads if asked.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import threading
20
+ import time
21
+ from argparse import ArgumentParser, Namespace
22
+ from concurrent.futures import ThreadPoolExecutor
23
+ from pathlib import Path
24
+
25
+ import numpy as np
26
+ from astropy.io import fits
27
+ from capn_crunch import add_options_to_parser, create_options_from_parser
28
+
29
+ from patchwork import __version__
30
+ from patchwork.coordinates import tile_coordinates
31
+ from patchwork.io import (
32
+ BeamShape,
33
+ ImageInfo,
34
+ check_output_fits,
35
+ create_output_fits,
36
+ read_block,
37
+ read_image_info,
38
+ suffixed_name,
39
+ write_block,
40
+ )
41
+ from patchwork.logging import logger, setup_logging
42
+ from patchwork.mosaic import add_log_level_argument
43
+ from patchwork.options import PolarisationOptions, RotateOptions
44
+ from patchwork.plan import group_inputs, input_frame_centre, rotates
45
+ from patchwork.polarisation import (
46
+ NORTH,
47
+ STOKES_CODES,
48
+ frame_angle,
49
+ rotate_linear,
50
+ write_frame_keywords,
51
+ )
52
+ from patchwork.resample import tile_threads
53
+ from patchwork.tile import PlaneWeight
54
+
55
+ ROTATE_BLOCK_BYTES = 256 * 2**20
56
+ """The memory the Q and U of one block of rows take while they are rotated, in float64"""
57
+
58
+
59
+ def rotated_name(path: str | Path, suffix: str = "rot") -> Path:
60
+ """The name of a rotated image: ``suffix`` inserted before a final ``.fits``, or added with ``.fits`` after any other name, so it never names the image itself."""
61
+ return suffixed_name(path, suffix)
62
+
63
+
64
+ def rows_per_block(info: ImageInfo, budget: int | None = None) -> int:
65
+ """The rows of an image rotated at once, so that the Q and U of a block fit in ``budget`` bytes (``ROTATE_BLOCK_BYTES``) as float64."""
66
+ ny, nx = info.shape
67
+ per_row = 2 * max(info.n_channels, 1) * nx * 8
68
+ budget = ROTATE_BLOCK_BYTES if budget is None else budget
69
+ return max(1, min(ny, budget // per_row))
70
+
71
+
72
+ def _output_beams(info: ImageInfo) -> tuple[BeamShape, ...]:
73
+ """The beams of the channels, to be recorded again in the output, or none to leave its header's as they are."""
74
+ beams = [beam for beam in info.channel_beams if beam is not None]
75
+ if len(beams) != len(info.channel_beams):
76
+ return ()
77
+ return tuple(beams)
78
+
79
+
80
+ def rotate_pair(
81
+ q_path: str | Path,
82
+ u_path: str | Path,
83
+ centre: tuple[float, float],
84
+ q_output: str | Path | None = None,
85
+ u_output: str | Path | None = None,
86
+ suffix: str = "rot",
87
+ overwrite: bool = False,
88
+ threads: int = 1,
89
+ reverse_rotation: bool = False,
90
+ ) -> tuple[Path, Path]:
91
+ """Rotate the Q and U of one input from north at ``centre`` to north at each pixel, writing new images.
92
+
93
+ This is the rotation ``patchwork mosaic`` applies to an input when it is
94
+ referenced to north at ``centre`` and the mosaic to north at each pixel.
95
+ The outputs copy the headers of the inputs, record the new frame in their
96
+ POLFRAME keywords, and are float32.
97
+
98
+ With ``reverse_rotation`` each pixel is turned by the same angle the
99
+ opposite way, to test the direction of the rotation. The outputs are then
100
+ not what ``patchwork mosaic`` would make, but record the same frame, and
101
+ their HISTORY says that the rotation was reversed.
102
+
103
+ Args:
104
+ q_path (str | Path): The Stokes Q image or cube
105
+ u_path (str | Path): The Stokes U image or cube, on the same grid
106
+ centre (tuple[float, float]): The (RA, Dec) in degrees whose north the Q and U are referenced to
107
+ q_output (str | Path | None, optional): Where to write the rotated Q. Defaults to None, ``rotated_name`` of the input.
108
+ u_output (str | Path | None, optional): Where to write the rotated U. Defaults to None, ``rotated_name`` of the input.
109
+ suffix (str, optional): The suffix of outputs that are not named. Defaults to "rot".
110
+ overwrite (bool, optional): Replace existing outputs. Defaults to False.
111
+ threads (int, optional): Threads that rotate blocks of rows at once; 0 uses every CPU. Defaults to 1.
112
+ reverse_rotation (bool, optional): Turn Q and U by minus the angle. Defaults to False.
113
+
114
+ Raises:
115
+ ValueError: Raised if the two images are not on one grid
116
+
117
+ Returns:
118
+ tuple[Path, Path]: The rotated Q and U
119
+ """
120
+ q_info, u_info = read_image_info(q_path), read_image_info(u_path)
121
+ if q_info.shape != u_info.shape or q_info.n_channels != u_info.n_channels:
122
+ msg = (
123
+ f"{q_path} is {q_info.shape} with {q_info.n_channels} channels but {u_path} is "
124
+ f"{u_info.shape} with {u_info.n_channels}; Q and U are rotated together, on one grid"
125
+ )
126
+ raise ValueError(msg)
127
+ outputs = (
128
+ Path(q_output) if q_output is not None else rotated_name(q_path, suffix),
129
+ Path(u_output) if u_output is not None else rotated_name(u_path, suffix),
130
+ )
131
+ for output in outputs:
132
+ check_output_fits(output, overwrite=overwrite, input_fits=[q_path, u_path])
133
+ for info, output in zip((q_info, u_info), outputs, strict=True):
134
+ header = info.header.copy()
135
+ write_frame_keywords(header, NORTH)
136
+ header["HISTORY"] = (
137
+ f"Rotated by patchwork {__version__} from north at RA {centre[0]:.5f}, "
138
+ f"Dec {centre[1]:.5f} to north at each pixel"
139
+ )
140
+ if reverse_rotation:
141
+ header["HISTORY"] = "The rotation was reversed, to test its direction"
142
+ create_output_fits(output, header, _output_beams(info))
143
+
144
+ ny, nx = q_info.shape
145
+ rows = rows_per_block(q_info)
146
+ blocks = [slice(start, min(start + rows, ny)) for start in range(0, ny, rows)]
147
+ threads = tile_threads(threads)
148
+ logger.info(
149
+ f"Rotating {q_path} and {u_path} from north at RA {centre[0]:.5f}, Dec {centre[1]:.5f} "
150
+ f"to north at each pixel{', with the rotation reversed' if reverse_rotation else ''}: "
151
+ f"{q_info.n_channels} channels in {len(blocks)} blocks of rows on {threads} threads"
152
+ )
153
+ with (
154
+ fits.open(outputs[0], mode="update", memmap=True) as q_hdul,
155
+ fits.open(outputs[1], mode="update", memmap=True) as u_hdul,
156
+ ):
157
+ q_hdu, u_hdu = q_hdul[0], u_hdul[0]
158
+ # Map the data once, before any thread writes to it
159
+ q_hdu.data # noqa: B018
160
+ u_hdu.data # noqa: B018
161
+
162
+ done = 0
163
+ counting = threading.Lock()
164
+
165
+ def rotate_block(block: slice) -> None:
166
+ nonlocal done
167
+ started = time.perf_counter()
168
+ region = (block, slice(0, nx))
169
+ angle = frame_angle(centre, tile_coordinates(q_info.wcs, region).vectors)
170
+ if reverse_rotation:
171
+ angle = -angle
172
+ q, u = rotate_linear(
173
+ np.asarray(read_block(q_path, region), dtype=np.float64),
174
+ np.asarray(read_block(u_path, region), dtype=np.float64),
175
+ angle,
176
+ )
177
+ write_block(q_hdu, region, q)
178
+ write_block(u_hdu, region, u)
179
+ with counting:
180
+ done += block.stop - block.start
181
+ rows_done = done
182
+ logger.debug(
183
+ f"Rotated rows {block.start}-{block.stop} of {q_path} and {u_path} "
184
+ f"in {time.perf_counter() - started:.1f} s; {rows_done} of {ny} rows "
185
+ f"({rows_done / ny:.0%}) done"
186
+ )
187
+
188
+ if threads > 1 and len(blocks) > 1:
189
+ with ThreadPoolExecutor(min(threads, len(blocks))) as pool:
190
+ # Consumed, so that a block that fails is raised here
191
+ list(pool.map(rotate_block, blocks))
192
+ else:
193
+ for block in blocks:
194
+ rotate_block(block)
195
+ for output in outputs:
196
+ logger.info(f"Written {output}")
197
+ return outputs
198
+
199
+
200
+ def rotate_cubes(
201
+ images: list[Path],
202
+ options: RotateOptions = RotateOptions(), # noqa: B008
203
+ overwrite: bool = False,
204
+ threads: int = 1,
205
+ ) -> list[Path]:
206
+ """Rotate the Q and U of images or cubes to north at each pixel, each written beside its input.
207
+
208
+ Images on one pixel grid are a pair, as ``patchwork mosaic`` groups them,
209
+ and the frame each pair is in comes from its POLFRAME keywords or the
210
+ options as it does there (``patchwork.plan.input_frame_centre``). Every
211
+ output is checked before any is written.
212
+
213
+ Args:
214
+ images (list[Path]): The Q and U images or cubes, in any order
215
+ options (RotateOptions, optional): What the inputs are referenced to, and how the outputs are named. Defaults to RotateOptions().
216
+ overwrite (bool, optional): Replace existing outputs. Defaults to False.
217
+ threads (int, optional): Threads that rotate blocks of rows at once; 0 uses every CPU. Defaults to 1.
218
+
219
+ Raises:
220
+ ValueError: Raised if an image is not of Q or U, a Q or U has no partner on its grid, or a pair is already referenced to north at each pixel
221
+
222
+ Returns:
223
+ list[Path]: The rotated image of each input, in the order given
224
+ """
225
+ infos = [read_image_info(image) for image in images]
226
+ linear = (STOKES_CODES["Q"], STOKES_CODES["U"])
227
+ others = [str(info.path) for info in infos if info.stokes not in linear]
228
+ if others:
229
+ msg = f"Only Q and U are rotated, but these are not: {', '.join(others)}"
230
+ raise ValueError(msg)
231
+ # Images matched by a pattern can include ones rotated before, so no output may be any input
232
+ for image in images:
233
+ check_output_fits(
234
+ rotated_name(image, options.suffix), overwrite=overwrite, input_fits=images
235
+ )
236
+
237
+ polarisation = PolarisationOptions(
238
+ input_frame=options.input_frame, frame_centre=options.frame_centre
239
+ )
240
+ pairs = []
241
+ for item in group_inputs(infos, [PlaneWeight()] * len(infos)):
242
+ if not rotates(item.stokes):
243
+ have = "Q" if STOKES_CODES["Q"] in item.stokes else "U"
244
+ msg = (
245
+ f"{item.info.path} is Stokes {have}, but there is no "
246
+ f"{'U' if have == 'Q' else 'Q'} on its pixel grid; both are needed to rotate"
247
+ )
248
+ raise ValueError(msg)
249
+ centre = input_frame_centre(item, polarisation)
250
+ if centre is None:
251
+ msg = (
252
+ f"The Q and U of {item.info.path} are already referenced to north at each "
253
+ "pixel, so there is nothing to rotate"
254
+ )
255
+ raise ValueError(msg)
256
+ q_path = item.planes[item.stokes.index(STOKES_CODES["Q"])]
257
+ u_path = item.planes[item.stokes.index(STOKES_CODES["U"])]
258
+ pairs.append((q_path, u_path, centre))
259
+
260
+ if options.reverse_rotation:
261
+ logger.warning(
262
+ "The rotation is reversed, to test its direction: the outputs record that they "
263
+ "are referenced to north at each pixel, but are turned the opposite way to the "
264
+ "rotation patchwork mosaic applies"
265
+ )
266
+ outputs: dict[Path, Path] = {}
267
+ for q_path, u_path, centre in pairs:
268
+ outputs[q_path], outputs[u_path] = rotate_pair(
269
+ q_path,
270
+ u_path,
271
+ centre,
272
+ suffix=options.suffix,
273
+ overwrite=overwrite,
274
+ threads=threads,
275
+ reverse_rotation=options.reverse_rotation,
276
+ )
277
+ return [outputs[info.path] for info in infos]
278
+
279
+
280
+ def get_parser(parser: ArgumentParser | None = None) -> ArgumentParser:
281
+ """The parser of the ``rotate`` command."""
282
+ if parser is None:
283
+ parser = ArgumentParser(description=__doc__)
284
+ parser.add_argument(
285
+ "images",
286
+ nargs="+",
287
+ type=Path,
288
+ help="The Q and U images or cubes to rotate, in any order; those on one pixel grid are a pair",
289
+ )
290
+ parser.add_argument(
291
+ "--overwrite", action="store_true", help="Replace existing output files"
292
+ )
293
+ parser.add_argument(
294
+ "--threads",
295
+ type=int,
296
+ default=1,
297
+ help="Threads that rotate blocks of rows at once; 0 uses every CPU",
298
+ )
299
+ return add_log_level_argument(
300
+ add_options_to_parser(parser=parser, options_class=RotateOptions)
301
+ )
302
+
303
+
304
+ def cli(args: Namespace | None = None) -> None:
305
+ """Run the ``rotate`` command."""
306
+ args = get_parser().parse_args() if args is None else args
307
+ setup_logging(args.log_level)
308
+ rotate_cubes(
309
+ images=args.images,
310
+ options=create_options_from_parser(
311
+ parser_namespace=args, options_class=RotateOptions
312
+ ),
313
+ overwrite=args.overwrite,
314
+ threads=args.threads,
315
+ )
316
+
317
+
318
+ if __name__ == "__main__":
319
+ cli()