:camera: image-classifier-ts readme

Command line tool to auto-classify images, renaming them with appropriate address and labels. Uses Node.js and the Google Geocoding and Vision APIs.

status - stable

image-classifier-ts is stable, with ongoing development (tested on Windows, Ubuntu Linux) following semantic versioning.

why?

The project was started as a way to avoid depending on particular photo software such as Picasa, and also to save time spent on sorting tons of photos!

dependencies

• Node 10.18.0 or higher
• Yarn

dependencies for Windows

We use sharp to resize images during processing. sharp requires node-gyp to build, so you will need to install Microsoft's windows-build-tools using this command:

npm install --global --production windows-build-tools

features

• process multiple image files and move them to a configurable folder, using a flexible filename template
• auto classify the image using the Google Vision API
• determine geographic location (address) of an image using the Google Geocoding API
• the output filename can include date, dimensions, file size as well as labels and adress provided by Google
• can take geographic locations from mobile photos and apply them to photos taken with a non-GPS device (matching by closest time for that date)
• supports JPEG, PNG file formats

usage - as cli (command line tool)

1 Configure your Google API key

see configure Google APIs.

2 Classify (label) your images

note: the processed images will be moved to the output directory. so you may want to point 'input directory' to a copy of your images directory.

3 ways to run

You can run image-classifier-ts in one of three ways:

• a) as a globally installed command line tool (this is the easiest way)
• OR b) as an npm package inside an npm project
• OR c) from the source code

a) install globally as a command line tool

npm i -g image-classifier-ts@latest --production

on Ubuntu, you may need administrator permissions via sudo:

sudo npm i -g image-classifier-ts@latest --production

To use:

image-classifier-ts <path to image directory> <path to output directory> [-filenameFormat=<file name format>]

OR b) from the npm package

Install inside your npm project:

yarn add image-classifier-ts

via bash script:

node_modules/image-classifier-ts/dist/lib/cli.js <input directory> <output directory>

OR via node:

node node_modules/image-classifier-ts/dist/lib/main <input directory> <output directory>

OR c) from the source code

yarn

On Windows: use a bash shell like git bash.

To test your installation:

./test.sh

To classify your images:

./go.sh <path to image directory> <path to output directory> [-filenameFormat=<file name format>]

example:

./go.sh ../myPhotos ../myPhotos-labelled

To have a 'dry run' where the images are not actually moved, use the 'dryRun' option:

./go.sh ../myPhotos ../myPhotos-labelled -dryRun

To see more detailed usage info:

./go.sh

example:

./go.sh ../my-photos -filenameFormat={year}/{location}/{topLabel}/{combinedLabels}-{fileSizeMb}-{width}x{height}--{filename}

advanced - specifying locations by date

You can specify locations for the photos, by date.

Do this by adding a file named mapDateToLocation.csv in the same folder as your images.

The approprite location description will be used when renaming the image files.

For an example, see mapDateToLocation.csv

note: if the location is unknown, and the filename format includes {location}, then the image will NOT be moved.

usage - as a library in a node based project

Install inside your npm project:

yarn add image-classifier-ts

Then in TypeScript, you can import the library:

import * as ic from "image-classifier-ts";

For a working example, see the library test harness.

sites

| site | URL | | -------------------- | ------------------------------------------------- | | source code (github) | https://github.com/mrseanryan/image-classifier-ts | | github page | https://mrseanryan.github.io/image-classifier-ts/ | | npm | https://www.npmjs.com/package/image-classifier-ts |

developing code in this repository

see the contributing readme.

origin

This project is based on the excellent seeder project typescript-library-starter.

libaries

image-classifier-ts uses the ExifReader library.

ORIGINAL readme (from the seeder project)

see here

authors

Original work by Sean Ryan - mr.sean.ryan(at gmail.com)

licence = MIT

This project is licensed under the MIT License - see the LICENSE file for details