Skip to content

README_EN.md

Latest commit

 

History

History
132 lines (86 loc) · 6.4 KB

README_EN.md

File metadata and controls

132 lines (86 loc) · 6.4 KB
Raw

PdfAutoRenameTools

English README | 中文说明

Are you still renaming downloaded research paper PDFs one by one by hand?

When you download papers in bulk from academic search engines, the resulting files often have uninformative names such as paper.pdf, document(1).pdf, or 2401.08392.pdf. To organize them manually, you usually need to open each PDF, find the title, close the file, and rename it. Even if one paper only takes about ten seconds, organizing hundreds of papers can easily consume an entire afternoon.

PdfAutoRenameTools solves this problem with one automated workflow.

The tool reads layout information from the first page of each PDF, identifies the paper title, and renames the file to that title. It supports batch processing without manual intervention, making literature organization much faster and more convenient.

Key Features

  • Intelligent title detection — Uses PDF text font size and coordinate information to locate the largest prominent text on the first page as the paper title.
  • Recursive batch processing — Scans an entire folder and its subfolders to process all PDF files in one run.
  • GUI and command-line modes — Provides both a graphical user interface and a command-line interface for different usage scenarios.
  • Parallel processing — Uses Java parallel streams to improve performance when processing large collections of papers.
  • Safer renaming workflow — In GUI mode, you can preview the proposed rename results before confirming the operation, reducing the risk of accidental changes.

Background

The core algorithm of this project is based on the original public version shared by Mr. Bingning Wang on his homepage. The original tool has been very useful in daily research work. During long-term use, one known issue was found: for some papers, the extracted title only included the first line, which caused incomplete renamed file names.

To fix this issue, the original JAR was reverse-analyzed with Luyten. After understanding the original source logic, the title extraction algorithm was specifically optimized, and a Swing-based graphical user interface was added to make the tool easier to use.

If Mr. Bingning Wang believes that publishing this code is inappropriate, the repository owner may be contacted to remove it.

Installation and Requirements

Runtime Requirement

A Java runtime environment is required to run the generated JAR files. The project documentation records the following Java environment as the compilation environment:

java version "26.0.1" 2026-04-21
Java(TM) SE Runtime Environment (build 26.0.1+8-34)
Java HotSpot(TM) 64-Bit Server VM (build 26.0.1+8-34, mixed mode, sharing)

Other Java versions may also work, but you should configure a suitable Java environment for your system.

JAR Location

The generated JAR files are located in:

out\artifacts\PdfAutoRenameTools_jar\

This directory contains the GUI and command-line JAR files:

PdfAutoRenameTools_GUI.jar
PdfAutoRenameTools.jar

Usage

Option 1: Graphical User Interface, recommended

Run the GUI version with:

java -jar PdfAutoRenameTools_GUI.jar

After the graphical interface opens:

  1. Click Select Folder to choose the directory that contains PDF files.
  2. Click Scan PDF to automatically detect the paper title for each PDF. The table will display each mapping from the original file name to the proposed new file name.
  3. After confirming that the preview results are correct, click Confirm Rename to perform the batch rename operation.

The table uses colors to show status:

  • Green: the file has been renamed successfully.
  • Red: the file failed or was skipped.

Option 2: Command Line

Run the command-line version with a target directory path:

java -jar PdfAutoRenameTools.jar <directory-name>

The program recursively scans all PDF files under the specified directory and renames them according to the detected title from the first page.

Example:

java -jar PdfAutoRenameTools.jar D:\Papers

How It Works

Core Algorithm

The title detection logic is implemented in TextLocationExtender.java:

  1. The class extends PDFBox PDFTextStripper and captures each text fragment during parsing, including its content, font size, X coordinate, and Y coordinate.
  2. All font sizes are sorted in descending order. The font size at the first one-third position is used as a threshold to filter out smaller body text.
  3. From the remaining text, the algorithm selects continuous text lines that are near the top of the page, based on the smallest Y coordinate, and share a consistent font size. These lines are then joined as the title.
  4. The extracted title is cleaned before being used as a file name. This includes removing hyphenated line breaks and replacing characters that are illegal in file names.

Source Code Structure

src/nlpr/cip/
├── Main.java                  # Command-line entry point
├── GuiMain.java               # Swing graphical user interface
├── TextLocationExtender.java  # Core PDF text parsing and title extraction logic
├── Pair.java                  # Data structure: text, font size, X coordinate, Y coordinate
└── utils.java                 # Recursive file and directory traversal utilities

Dependencies

Library Version Purpose
Apache PDFBox 2.0.23 PDF parsing and text extraction
Apache Commons Logging 1.2 Logging framework
FontBox 3.0.0-RC1 PDF font information handling

The repository also includes related JAR dependencies such as pdfbox-app-2.0.23.jar, commons-logging-1.2.jar, and fontbox-3.0.0-RC1.jar.

Notes and Limitations

  • The title detection method is heuristic. It works by analyzing first-page layout information, especially font size and position.
  • Papers with unusual layouts, scanned image-only PDFs, missing embedded text, or non-standard title formatting may not be detected correctly.
  • GUI mode is recommended when processing important files because it allows you to preview rename results before applying them.
  • Before running batch renaming on a large folder, consider testing the tool on a small sample or keeping a backup of your files.