psm-image-picker

A tool that is capable of outputting a list of images based on specified search criteria.

What is psm-image-picker?

It's a CLI tool being developed for the purpose of completing a code challenge by a potential employer. This tool follows the following criteria:

Expected input

1. Number of images to output
2. Image keywords to match as a comma-separated-value, i.e. "blue, flowers, desert"

Expected output

1. Total number of results
2. Image URL
3. Image Width
4. Image Height

How can I use psm-image-picker?

You can use it as a command line tool to do the grunt work for you without writing a single line of code OR you can use this as a regular node package if you're trying to achieve something a little more custom.

CLI Tool

Installation

To use psm-image-picker as a command line tool, perform the following command on a machine that has node and npm installed on it:

npm install psm-image-picker -g

After doing so, you can browse the cli tool help by performing psm-image-picker --help.

General Usage

To use psm-image-picker as a command line tool, you need to specify the following parameters:

psm-image-picker -i /path/to/image/dictionary.json -k 'blue, desert' -n 20

The above command will search the specified image dictionary for images with the keywords 'blue' and 'desert'; then, it returns a maximum number of 20 results.

If you wanted to search for images of a certain size, you'd just add a few additional parameters like so:

psm-image-picker -i /path/to/image/dictionary.json -k 'blue, desert' -n 20 -h 400 -w 1000

The above command will perform the same search as the first example above BUT this time it will limit the results to images that have up to a height of 400 and up to a width of 1000.

Note that it is possible to use just -h (or --height) or -w (or --width) or both.

Output

If you did not specify an output file with -o /path/to/save/output/file.json, the results are listed directly in the console.

If you'd like to save the results of a search, modify your command to include the -o (or --output) flag, like so:

psm-image-picker -i /path/to/image/dictionary.json -k 'blue, desert' -n 20 -o /path/to/save/results.json

Note that in the command above, /path/to/save must be a valid directory for the output to be saved correctly.

Node.js Package

Installation

To include psm-image-picker in your node.js application, run the following command:

npm install psm-image-picker --save

General Usage

To use this package in your node.js application, you can do something like this:

// external dependencies
const PsmImagePicker = require('psm-image-picker');

// setup some variables to make life easier
const imageDictionary = [
  {
    url: 'http://some.url/image.png',
    size: {
      height: 150,
      width: 400
    },
    keywords: [
      'blue', 'flowers', 'desert'
    ]
  }, {
    url: 'https://some.url.somewhere/image.jpg',
    size: {
      height: 400,
      width: 1000
    },
    keywords: [
      'blue', 'foobar'
    ]
  }
];

// setup a new image picker with the specified image dictionary
const myImagePicker = new PsmImagePicker(imageDictionary);

// search for images with the keywords "blue" and "flowers"
// and return a maximum of 10 results.
myImagePicker.search(['blue', 'flowers'], 10);

Note that the code example above indicates an instantiation that uses an object literal to define the image dictionary. It is also possible to load the configuration via a JSON file by performing something like this:

// external dependencies
const PsmImagePicker = require('psm-image-picker');

// internal dependencies
const imageDictionaryA = require('./path-to-my.json'); // (note the `.`)
const imageDictionaryB = require('./path-to-my-json'); // (note no period)

// setup a new image picker with the specified image dictionary
const myImagePickerA = new PsmImagePicker(imageDictionaryA);
const myImagePickerB = new PsmImagePicker(imageDictionaryB);

// perform a few searches and concatenate the results (note that `allResults`
// may need to be reordered to maintain consistency)
// and return a maximum of 10 results.
var resultsA = myImagePickerA.search(['blue', 'flowers'], 10);
var resultsB = myImagePickerB.search(['desert'],
var allResults = resultsA.concat(resultsB);

API

1. .search(maxResults) - Searches the image dictionary for a known number of results.

• maxResults - an positive integer that indicates the maximum number of results to return

1. .search(keywords) - Searches the image dictionary for all images that have the specified keywords.

• • keywords - an array of keywords (strings) to search for, ie - ['blue', 'flowers']

1. .search(size) - Searches the image dictionary for all images that fit within the specified size constraints.

• size - an object literal with either (or both) keys height & width. If height is a property of this object, the search will attempt to find images that fit within the specified height. If width is a property of this object, the search will attempt to find images that fit within the specified width. ie - {height: 450}, {width: 500} or {height: 450, width: 500}

1. .search(keywords, maxResults) - Searches the image dictionary for images that fit the meta

• keywords - an array of keywords (strings) to search for, ie - ['blue', 'flowers']
• maxResults - an positive integer that indicates the maximum number of results to return

1. .search(keywords, size) - Searches the image dictionary for images that fit the meta

• keywords - an array of keywords (strings) to search for, ie - ['blue', 'flowers']
• size - an object literal with either (or both) keys height & width. If height is a property of this object, the search will attempt to find images that fit within the specified height. If width is a property of this object, the search will attempt to find images that fit within the specified width. ie - {height: 450}, {width: 500} or {height: 450, width: 500}

1. .search(size, maxResults) - Searches the image dictionary for images that fit the meta

• size - an object literal with either (or both) keys height & width. If height is a property of this object, the search will attempt to find images that fit within the specified height. If width is a property of this object, the search will attempt to find images that fit within the specified width. ie - {height: 450}, {width: 500} or {height: 450, width: 500}
• maxResults - a positive integer that indicates the maximum number of results to return

1. .search(keywords, maxResults, size) - Searches the image dictionary for images that fit the meta

• keywords - an array of keywords (strings) to search for, ie - ['blue', 'flowers']
• maxResults - a positive integer that indicates the maximum number of results to return
• size - an object literal with either (or both) keys height & width. If height is a property of this object, the search will attempt to find images that fit within the specified height. If width is a property of this object, the search will attempt to find images that fit within the specified width. ie - {height: 450}, {width: 500} or {height: 450, width: 500}

Docker

If you'd like to run psm-image-picker inside a docker container, checkout the official Docker Hub repository.

License

The MIT License (MIT)

Copyright (c) 2017 Carl Danley

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.