Skip to content

Home

Jump to bottom
Rodney Kan edited this page Oct 31, 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.

Outline

Simple method
Customized method
Configuration
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. 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}}
  
  }

}

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.

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

Configuration

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

  • n: the frequency to have image search, the lower the more frequent doing search

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

  • n: image url count per search

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 pictures and program files (.pickle) reside

[image]
slideshow_frequency=n (default: 10)

  • n: the frequency in second to have slideshow

[phrase]
ratio=n (default: 100)

  • n: a fixed percentage ratio (0-100) to show phrase

font_size=n (default: 64)

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

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 Configuration->search->search_unit_size. Also search rate can be changed by Configuration->search->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 bigger search_latency, and then the overall search rate will be lower.
Clone this wiki locally