Skip to content

Home

Jump to bottom
Rodney Kan edited this page Nov 5, 2016 · 48 revisions

Welcome to the iReminder wiki!

The feature of iReminder is constructed by image and phrase specification. In general, it can be made in two ways, simple and customized: for simple method, raw text is specified; for customized method, each raw text is attached with properties to replace default behavior.
Certain general setting is configurable, for example, the slideshow frequency, and the font size of phrases.
On screen functions are also available, for example, show next image, and delete image.

Installation

You need python2.7 with Tcl/Tk installed to run iReminder.
In Unix-like system, the following does the installation.
apt-get install python-tk
apt-get install python-imaging-tk

Some assistant modules are required. They can be installed via pip as follows:
python setup.py install

Outline

Simple method
Customized method
Settings
On screen functions
FAQ

Let's start from the basic usage.

Simple method

Raw text can be specified by command line, or by list files (.list) such that each raw text is separated by new line:

iReminder image [image] [-p phrase]

For example,

iReminder cat -p "what kind of cat shall I adopt?"

or

iReminder color_of_cats.list -p name_of_cats.list

// file 'cat.list'
black cat
brown cat

// file 'cat_names.list'
name it 'Puppy'?
name it 'Yummy'?

The simple method adopts an ‘even’ way: each image and phrase is selected in equal chance. On the other hand, the customized method breaks even by specifying weights. It also provides flexibility in searching images and generating sentences.

Customized method

The customized method utilizes the json file format by

iReminder image.json [image.json] [-p phrase.json]

Detailed documentation in terms of JSON Schema is available here. In the following, we will go through the major feature through examples.

If one pattern is expected to appear two times more than the other, for example, we can have the following:

// file 'image_weight.json'
{

  "image":

  {

    "patternA": {"rank": {"kind": "WEIGHT", "value": 1}},

    "patternB": {"rank": {"kind": "WEIGHT", "value": 2}}

  }

}

By specifying PERCENTAGE, an absolute appearance ratio is given among all patterns.

// file 'image_percentage.json'
{

  "image":

  {

    "patternC": {"rank": {"kind": "PERCENTAGE", "value": 25}},

    "patternD": {"rank": {"kind": "PERCENTAGE", "value": 50}}

  }

}

Download files: image_weight.json, image_percentage.json

If phase is expected to be attached with certain, not all image, we can group it in sentence and specify the target property with the image pattern.

// file 'phrase_target.json'
{

  "phrase with target":

  {

    "target": ["patternA", "patternD"],

    "sentence": "This sentence applies for patternA and patternD images"
  }

}

An inspiring way is to relate phrases with images.

// file 'image_animation.json'
{

  "image":

  {

    "Wreck-It Ralph": {"attribute": {"main_actor": ["Ralph", "Vanellope"]}},
    "Inside Out": {}

  }

}

// file 'phrase_dynamic.json'
{
  "dynamic phrases":

  {

    "target": "image_animation",

    "sentence":

    {

      "var(main_actor)：I starred in var(`pattern)!":
      {
        "default_value": {"main_actor": "main actor of var(`pattern)"}
      }

    }

  }
}

Here, main_actor is the attribute property of image. It is enclosed by the var(, ) pair in phrase_dynamic.json to build a more creative sentence. In addition, var(`pattern) resolves to the selected image pattern. default_value shall be specified when corresponding attribute does not exist for certain target patterns.

Download files: phrase_target.json, image_animation.json, phrase_dynamic.json

The most important entry in program setting is the GCS certificate, i.e., cx and api_key. Other entry gives general control how images and phases are processed.

Settings

[search]
api_key=api_key acquired from GCS
cx=cx acquired from GCS
latency=n (default: 3)

  • n: the latency to have image search; the lower the more frequent doing search

search_size=n (default: 10, minimal: 10)

  • n: image url count per search

img_size=img_size (default: xlarge)

  • img_size: value(s) from icon, small, medium, large, xlarge, xxlarge, huge, separated by '|'
  • example: large|xlarge

[global]
data_location=home

  • home: the directory retrieved pictures and program files (.pickle) reside in

[image]
slideshow_rate=n (default: 10)

  • n: the interval in seconds have slideshow

[phrase]
attach_rate=n (default: 100)

  • n: a fixed percentage (0-100) to attach image with phrase

font_size=n (default: 32)

  • n: font size in pixel

At run time, several viewing related functions are provided. They are enabled/disabled through specific keyboard buttons.

On screen functions

function key
pause | continue p | P
next picture -> (right arrow)
previous picture <- (left arrow)
increase picture rank +
decrease picture rank -
remove picture (Windows | Linux) backspace
remove picture (OSX) delete
switch fullscreen esc
switch on screen help h | H
switch on screen info i | I
quit program q | Q

The following section covers some technical details. Check if you are interested to corresponding topics.

FAQ

  • How to apply for a Google Custom Search api_key and cx?

    • Sign-up/Sign-in an account for Google API Console.
    • In the Credential page, click Create credentials to get api_key.
    • Go to the Custom Search Engine homepage, create a search engine.
    • In the Edit search engine page
      • In the Image search section, switch image search to ON.
      • Select Search the entire web but emphasize included sites.
      • Get cx (the search engine ID).
    • Back to the API Console page, enable Custom Search API in the Dashboard page.

  • When and how Google Custom Search is issued?

    • As Google Custom Search (GCS) is either paid or free in limited requests, iReminder adopts a conservative way in issuing a search.
    • Conceptually, a search with less new result takes longer time till next search. In some sense it then guarantees little wasted requests. In practice, the number of retrieved image urls per search in iReminder is configurable with a minimum value 10 (each GCS request gets 10 results) by Setting->search->search_size. Also search rate can be changed by Setting->search->latency, if the default setting does not make use of GCS very well.
    • For example, a typical free account has a limit of 100 requests per day. If we configure iReminder to obtain 60 image urls per search (means there are actual 6 GCS request), we can search up to 100 / 6 = 16 image patterns. Meanwhile, if somehow there is a lot more patterns than 16, then some of them may have little chance to search, due to the limit can be so quick to be reached. To alleviate the situation, we can make latency bigger, and then the overall search rate will be lower.
Clone this wiki locally