Any interest in adding support for rotating PDF pages?

[hwine]

It's amazing how much I've used pdfly without noticing it did not have support for rotating pages. 😁. Recently I did, and coded a short script to do the job (use case below), also using pypdf to do the real work. The rotation is actually trivial -- what is a challenge is figuring a good UX for it.

I ended up with some bash 1-liners to:

• split an original file into 1 page files using pdfly
• rotate even/odd pages correctly using my script
• assembling a final rotated version, again using pdfly

If this feature would be of interest, I'd be happy to do a PR -- after discussing the UX options, of course. (Please indicate if you'd prefer the UX discussion in "discussions" or as an "issue" -- assuming you're interested.)

A use case for rotation

I've recently started to use paperless-ngx for personal use which works great with my scanner except for 1 case:

• if the document to be scanned is printed in landscape mode, and
• the document is 2 sided configured for top binding, then
• the PDF is rendered portrait format, with alternating pages being rotated clockwise (CW) or counter-clockwise (CCW).

To take advantage of the OCR capabilities of paperless, I need to present a PDF with all the pages right-side-up. As indicated above, this can be done manually, if one is comfortable with the command line. It would be a much nicer UX if pdfly could do it in one pass.

[Lucas-C]

Hi @hwine

Thank you for reaching out!

That would be a very welcome addition 🙂

Regarding the UX, maybe we could have a rotate subcommand, with a similar syntax as the cat subcommand: pdfly rotate $pdf_filepath $degrees [$page_ranges] [-o $output_filepath]:

• pdfly rotate input.pdf 90 would rotate ALL pages by 90° of input.pdf inplace (= overwriting the file)
• pdfly rotate input.pdf 180 ::2 -o output.pdf would rotate all even pages by 180° of input.pdf and write the result output.pdf

What do you think about this @hwine?

Note that we already rotate pages in pdfly source code, e.g. in the booklet subcommand.

[hwine]

I think that UI would be fine. I would suggest adding another subcommand (or option to rotate) that would allow "single pass" for my use case. That is, where every even page needs to be rotated one way, and the odd pages rotated the other way. Maybe:

• pdfly rotate input.pdf -a 90 -o output.pdf where "-a" is for "alternate", and "90" is the direction to rotate the first (odd) page. (The even pages would be rotated -90.)

Related, do you have any strong feelings about having "CW" & "CCW" be synonyms for 90 & -90 respectively? (clockwise & counter clockwise -- I know analog clock faces are less common these days, so I don't feel strongly on the subject.)

I'll get started (slowly 😉). I expect I'll have questions around the testing, as I'm not PDF internals literate.

[Lucas-C]

I would suggest adding another subcommand (or option to rotate) that would allow "single pass" for my use case.

I'm not sure that this would be necessary.
I would prefer to keep the command simple.
This could be easily done by simply making 2 successive calls:

pdfly rotate input.pdf 90 ::2 -o output.pdf
pdfly rotate output.pdf -90 1::2

Related, do you have any strong feelings about having "CW" & "CCW" be synonyms for 90 & -90 respectively? (clockwise & counter clockwise -- I know analog clock faces are less common these days, so I don't feel strongly on the subject.)

I would prefer to avoid using acronyms, that would not be immeditaly understood by a first-time user of pdfly.
Don't you think that using arc degrees to specify rotations should be enough, and universally understood?

I'll get started (slowly 😉). I expect I'll have questions around the testing, as I'm not PDF internals literate.

Great!
Thank you for working on this.
Please ask if you have any question 🙂

[hwine]

I'm not sure that this would be necessary. I would prefer to keep the command simple. This could be easily done by simply making 2 successive calls:

pdfly rotate input.pdf 90 ::2 -o output.pdf
pdfly rotate output.pdf -90 1::2

You are right -- it isn't necessary. However, it does require an understanding of Python specific slicing notation. I'll leave it out for now.

Don't you think that using arc degrees to specify rotations should be enough, and universally understood?

Well, except for folks who will assume radians in any trig context 😉.

I'll keep it simple to start -- it can always be embellished later.

[Lucas-C]

Sounds great! 🙂

[hwine]

@Lucas-C I've got it basically working in my fork, but have a few questions about argument processing. I'll push to a draft PR soonish, but wanted to get this question asked.

A number of your examples in this discussion thread implied that the --output option was optional, and would default to updating in-place. However, the code shows that most sub-commands require the --output option (see below). And in the cat sub-command, not specifying an output path results in output to STDOUT.

Personally, I prefer to neither default to overwrite nor default to STDOUT (for binary formats). Which of the 3 approaches would you want for the new rotate sub-command?

Current handling of "--output" option

$ for cmd in extract-images 2-up cat booklet rm meta pagemeta extract-text compress uncompress update-offsets x2pdf extract-annotated-pages rotate; do echo $cmd; pdfly $cmd --help | grep -- --output | sed -r 's/\s*\|\s*//'; done
extract-images
2-up
cat
  *  --output    -o                  PATH  [default: None] [required]
booklet
rm
  *  --output   -o                  PATH  [default: None] [required]
meta
  --output  -o      [jsontext]  output format [default: text]
pagemeta
  --output  -o      [jsontext]  output format [default: text]
extract-text
compress
uncompress
update-offsets
  --output    -o                  PATH  [default: None]
x2pdf
  *  --output  -o      PATH  [default: None] [required]
extract-annotated-pages
  --output  -o      PATH  Output PDF file. Defaults to 'input_pdf_annotated'.
rotate
  *  --output  -o      PATH  [default: None] [required]
$

[Lucas-C]

Sorry for the delay in answering.

For commands that perform modifications on PDF files (not like cat or rm), I think that defaulting to in-place updating the PDF file is a fine default.

[hwine]

@Lucas-C Another change I made is I extended the pagemeta subcommand to report out the page's "rotation" value, since it can now be manipulated by pdfly. Let me know if you'd prefer that work in a separate PR.

[Lucas-C]

That's nice, great idea!

[hwine]

My turn for "sorry for the delay" 😬 I'm starting to have less time, so want to get what I have up for review. See notes in the PR for actual status.

I just pushed a PR #128, where further comments should go.