Skip to content

Latest commit

 

History

History
193 lines (139 loc) · 7.97 KB

README.adoc

File metadata and controls

193 lines (139 loc) · 7.97 KB
Raw

FileRename

About the Project

Aim of this project is to provide a mapping solution between the various image naming patterns of mobile device and camera manufacturers. Since most manufacturers do not support defining a custom file naming pattern, having several different devices can lead to highly different file names for images that were e.g. taken in close temporal proximity.

The aims of this application are twofold:

  • Firstly, the application should provide a command line based solution for this issue, especially with regards to different timestamp formats. This solution is intended to be run automatically, e.g. after importing images from a device or as cron job.

  • Secondly, the application should allow extending and manipulating the ruleset for such transformations easily.

Getting Started

Prerequisites

This project requires

  • Java Version 17

  • Maven

Installation

To generate an executable jar using maven simply

  1. Clone the repository

    git clone git@github.com:kocmana/filerename.git

  2. Compile and package the application

    mvn clean package

  3. Navigate to the /target folder and execute the filerename-with-dependencies.jar with one or several of the arguments described in the next section, eg:

    java -jar filerename-with-dependencies.jar -i "image<<TS|yyyyMMdd_HHmmss>>.jpg" -o "<<TS|yyyyMMdd_HHmmss>>" -d

How To Use

Several command line arguments can be used to customize the behavior of the application:

Usage: filerename [-hV] ([-p=<path>] [-r] -i=<inputTemplate>
                    -o=<outputTemplate> [-d] [-cp])...
      -cp, --copy     Define the operation to be performed. If set, files will
                        be copied instead of renamed.
  -d, --dryRun        Setting this parameter will only display how the file
                        names will be changed without performing any changes
  -h, --help          Show this help message and exit.
  -i, --input=<inputTemplate>
                      The pattern of the input file names
  -o, --output=<outputTemplate>
                      The pattern of the output file names
  -p, --path=<path>   The directory for the operation
  -r, --recursive     Include sub directories.
  -V, --version       Print version information and exit.

Examples

Single Task
java -jar filerename-with-dependencies.jar -i "image_<<TS|yyyyMMdd_HHmmssSSS>>.jpg" -o "<<TS|yyyy-MM-dd_HH-mm-ss>>.jpg" -d -cp

  • -i/-o: Input and Output filename patterns

  • -d: Dry run: This task will let you check if the result is what you expect it to be without performing any actual changes to the files specified

  • -cp: This task will create copies of the specified files using their output filenames rather than renaming them.

Multiple Tasks
java -jar filerename-with-dependencies.jar -i "image_<<TS|yyyy-MM-dd>>.jpg" -o "<<TS|dd-MM-yyyy>>.jpg" -p "./user1/DCIM" -r -i "<<TS|yyyy-MM-dd_HHmmss>>.jpg" -o "<<TS|dd-MM-yyyy>>.jpg" -p "./user2/DCIM"

  • -i/-o: Input and Output filename patterns for both tasks

  • -p: Specify a path for the task, relative to the directory the jar is in

  • -r: Include subdirectories

Available Templates/Transformation Rules

Regex Transformation Rule - <<R|{regular_expression}>>

This rule allows to define a regular expression against which the filenames are matched.

This can be used in two ways:

  • Either only as part as the input pattern to match several files. Subsequently, other rules can be defined in the output pattern to modify these files:

    InputPattern OutputPattern Filename Resulting Filename

    IMAGE_<<R|[0-9]{3}>>.jpg

    picture-<<CD|yyyy-MM-dd>>.JPG

    IMAGE001.jpg

    picture-2020-10-21.JPG

  • As part of both input and output pattern: This allows to shift a defined char sequence in many files following the same pattern to a different position if the output pattern.

    InputPattern OutputPattern Filename Resulting Filename

    IMAGE_<<R|[0-9]{3}>>.jpg

    <<R>>-picture.JPG

    IMAGE_001.jpg

    001-picture.JPG

Timestamp Transformation Rule - <<TS|{timestamp_pattern>>

This rule allows defining source and target timestamp patterns based on the Java API patterns for formatting and parsing date and time information.

Example:
InputPattern OutputPattern Filename Resulting Filename

img<<TS|ddMMyyyyHHmmssSSS>>.jpg

image<<TS|yyyy-MM-dd_HHmmss>>.jpg

img20122021125401451.jpg

image2021-12-20_125401.jpg

File Creation Date Transformation Rule - <<CD|{timestamp_pattern}}>>

If no timestamp is available as part of the filename, the file creation date can be used instead.

If no timestamp_pattern is provided, ISO_DATE_TIME will be used per default.

👉
 The creation date of a filename is not necessarily the date the file (e.g. picture) was originally created. It commonly indicates when a file was created on any given system instead.
Example:
InputPattern OutputPattern Filename Resulting Filename

file<<R|[0-9]{5}>>.png

image_<<CD|yyyy-MM-dd_HHmmss>>.png

file00019.png

image_2021-12-20_125401.png

Enumeration Transformation Rule - <<E|{format_string_syntax}>>

This rule allows to add increasing numbers to the filename. Additional formatting arguments can be provided using the Java Format String syntax . If no formatting argument is provided (<<E>>) only the number itself will be used (synonymous with <<E|%d>>).

Example:
InputPattern OutputPattern Filename Resulting Filename

birthday_<<R|(.+)>>.png

image_<<E|%02d>>.png

birthday_1999-12-7-127.png

image_01.png

birthday_<<R|(.+)>>.png

image_<<E>>.png

birthday_1999-12-7-127.png

image_1.png

How to Extend the Ruleset

New rules/patterns can be added easily:

  1. You can implement the logic for the transformation rules using two approaches:

    1. Add a new transformation rule by implementing all required methods of the TransformationRule interface

    2. Add a new transformation rule by extending the AbstractTransformationRule class. This class provides several utility functions that allow you to focus on implementing the actual logic.

  2. Add the generator function to the TransformationRuleFactoryConfiguration in the form of a TransformationRuleGenerator that consumes the input and output pattern provided as String and provides an Optional<TransformationRule> as result. Please take the contract of the API into consideration to ensure proper functionality:

    • return Optional.empty() if the pattern provided does not indicate that the rule is applicable to the task

    • return Optional.of(yourRuleInstance) in cases where the rule is applicable to the task

    • throw an IllegalArgumentException in cases where the input and/or output string does clearly indicate wrong input that can’t be parsed (e.g. image<<ddMMyyyy.jpg for a timestamp transformation rule)

🚨
 Rules will be applied in parallel. Ensure sufficient atomicity where needed.
💡
 Rules will be created once per task and hence share a common state which allows for the creation of rules that e.g. depend on the number of other invocations.