The deeper problem is that even though FOD reorientation now has to be specified explicitly, whether or not it has to be specified still depends on the number of volumes, which remains a source of unexpected behaviour.

From the perspective of using the command directly, whether or not providing that option is necessary is entirely expected behaviour to me, as it only applies in cases where the command cannot unambiguously determine what the user wants it to do. It's merely an additional source of complexity for which the dwifslpreproc script was not updated.

Let's elucidate the options fully:

1. mrtransform retains current behaviour. An error is raised only if the input image could plausibly be an FOD image and -reorient_fod is not provided. Providing -reorient_fod for an input image that couldn't plausibly be an FOD image silently does nothing. dwifslpreproc always passes the -reorient_fod option so that it works on a dataset such as that described.

2. Within mrtransform, if the input image could plausibly be an FOD image, and -reorient_fod is not specified, additionally check whether or not the input image has a valid dw_scheme. If it does, print a console message / warning that FOD reorientation is not being used due to the presence of a gradient table, and proceed; if it does not, raise an error as previously.
   This is however not a complete solution: dwifslpreproc would however still need to be modified as per 3. below, since the SE-EPI image could come from anywhere.

3. mrtransform retains current behaviour. dwifslpreproc (and indeed any MRtrix3 or external script that calls mrtransform) is responsible for detecting if the input image could conceivably be mis-interpreted as an FOD image, and provides -reorient_fod false only in that scenario.

At this point in time I would probably advocate for 1. in order to solve this specific issue. If at some point in the future we have some back-end mechanism for flagging command-line options that were used to no effect, this would need to be revisited.

As with all such problems, we would also ideally add to the script testing suite a dwifslpreproc invocation that currently fails due to this error and is resolved with the proposed fix...

Slight correction to the current behaviour (1.): if -reorient_fod yes is given an error is thrown, -reorient_fod no is ignored. So the option is not entirely ignored.

I am also in favour of 1. -- 2. adds another layer of complexity and 3. makes writing scripts more painful, especially outside the MRtrix scripting library.

The problem I have with the current approach is this scenario:

A user develops a script or pipeline that mrtransforms an x * y * z * 5 dataset that has no bearing with FODs. This 5 can be a number of parameters or subjects or just images in general.

After the parametrization or number of subjects or images changes to 6, suddenly the script breaks and the user has to supply FOD related options even though the application has nothing to do with FODs.

The cleanest option on my opinion would be to merely print a warning if mrtransforming something that could be SH coefficients.

This is less of an evil than the behaviour changing from pre 3.0.0 where FOD reorientation was the default to post 3.0.0 where it would be off by default.

Reorientation might be easy to miss in scripts, a straight out error is easy to fix. I prefer slightly annoying syntax but easy to fix over potentially harmful behaviour. I suggest we replace the error by a warning in 3.1 or so but keep it for now. We had a discussion about this here.

This is less of an evil than the behaviour changing from pre 3.0.0 where FOD reorientation was the default to post 3.0.0 where it would be off by default.

Reorientation might be easy to miss in scripts, a straight out error is easy to fix. I prefer slightly annoying syntax but easy to fix over potentially harmful behaviour. I suggest we replace the error by a warning in 3.1 or so but keep it for now. We had a discussion about this here.

I agree completely. I wasn't implying that we change anything other than the current fix to address the bug. I was just thinking that in the long run, it would make slightly more sense to replace the error with a warning.