Table of Content

MetaFS::Cloud

THIS IS A PRELIMINARY DOCUMENT

VERSION: PRELIMINARY (2016/09/13)

NOTE: This API is subject to changes until version 1.0 is declared, likely beginning 2017.

1. Introduction

MetaFS::Cloud is a platform to enable cloud-based computing (REST API) of services such as computation intensive tasks like semantic text, image, audio or video analysis, for large deployments of MetaFS infrastructure where the clients relay some of the analysis to a private cloud infrastructure.

◹
MetaFS::Cloud in enterprise application

2. Services

Each service is available via

The default port is 20840.

All responds include: 

{
   ...
   "server" : {
      "app" : "ping",
      "elapsed" : 0.0241835635
      "time" : 1462869434.36302,
      "version" : "MetaFS::Cloud 0.0.3"
   }
   "status" : {
      "code" : 200,
      "mesg" : "OK"
   }
}

If the cloud server runs on the same physical machine, then the file can be reference by absolute filename (starting with /) as well (and omit '@'): 

% curl -F key=yourapikey -F image=`pwd`/test.jpg http://localhost/<someservice>
{
   ...
}

2.1. Ping

Simple ping, for testing your private cloud or testing commercial service.

  • Endpoint: http://localhost:20840/ping
  • API:
    • Input:
      • any kind of input
    • Output:
      • results
        • input contains all the input
        • time current server time in UNIX epoch
Example 
% cat test.txt
hello world!

% curl -F key=1234 -F 'arg=1' -F '[email protected]' -F _pretty=1 http://localhost:20840/ping
{
  "results" : {
      "input" : [
         {
            "_pretty" : "1", 
            "arg" : "1",
            "filename" : {
               "text" : "test.txt"
            },
            "key" : "1234",
            "text" : "hello world!",
            "types" : {
               "text" : "text/plain"
            }
         }
      ],
      "time" : 1462869434.36302
   },
   "server" : {
      "app": "ping",
      "elapsed" : 0.00170691,
      "time" : 1462869434.36302,
      "version" : "MetaFS::Cloud 0.0.3"
   },
   "status" : {
      "code" : 200,
      "mesg" : "OK"
   }
}
and without _pretty=1: 
{"results":{"input":[{"arg":"1","filename":{"text":"test.txt"},"key":"1234","text":"hello world!",\
"types":{"text":"text/plain"}}],"time":1462869434.36302},"server":{"app":"ping","elapsed":0.000804901123046875,\
"time":1462869434.36302,"version":"MetaFS::Cloud 0.0.3"},"status":{"code":200,"mesg":"OK"}}

Perl API: 

use MetaFS::Cloud;

my $c = new MetaFS::Cloud({host=>'localhost'});

my $r = $c->rpc('ping',{key=>1234,arg=>1,text=>"hello world!\n"});

print toJSON($r);
outputs the same JSON.

2.2. Sentiments

Extended text sentiment conclusion using MetaFS::Semantics::Sentiments currently.

  • Endpoint: http://localhost:20840/sentiments
  • API:
    • Input:
      • text: UTF-8 encoded text (max. 32MB)
      • lan (optional, but recommended): 2 letter abbreviation (ISO ..) of the language ('en' = default)
      • key (optional): must be provided if apiKeyRequired is enabled on server side
    • Output:
      • sentiments:
        • polarity:
          • conclusion: positive, negative, neutral (too close to call) or none
          • summary: in percentage (-100% .. 100%), computational summary
        • positive: in percentage (0 .. 100%), positive+negative = 100%
        • negative: in percentage (0 .. 100%)
        • intellectual: in percentage (0 .. 100%), abstract & intellectual
        • analytical: in percentage (0 .. 100%), objective without personal attachment
        • emotional: in percentage (0 .. 100%), subjective, personal and emotional
        • affirmative: in percentage (0 .. 100%), subjective, motivational, more subtle positive
        • poetic: in percentage (0 .. 100%), artistic, aiming for transcendence
        • shallow: in percentage (0 .. 100%), overused term(s), superficial
        • _quality: in percentage (0 .. 100%), gives an idea of how good the sentiment conclusion is
        • _stats: provides some absolute numbers
          • _all: total amount of checked words
          • _match: total amount of words which were determined to have sentiments
Examples 

% curl -H "Content-Type: application/json" -F key=yourAPIKey \
       -F [email protected] http://localhost:20840/sentiments
{
   "sentiments": {
      "affirmative" : 1,
      "emotional" : 0.538461538461539,
      "intellectual" : 0.384615384615385,
      "negation" : 0.154995720071263,
      "negative" : 0.230769230769231,
      "polarity" : {
         "conclusion" : "positive",
         "summary" : 0.5
      },
      "positive" : 0.692307692307692,
      "_quality" : 0.684210526315789,
      "_stats" : {
         "_all" : 190,
         "_match" : 13,
         "affirmative" : 3,
         "emotional" : 1,
         "intellectual" : 1,
         "negation" : 1,
         "negative" : 3,
         "positive" : 9
      }
   },
   "server" : {
      "elapsed" : 0.3762518,
      "version" : "MetaFS::Cloud 0.0.1"
   }
}

2.3. Topics

Topics conclusion using MetaFS::Semantics::Topics currently.

  • Endpoint: http://localhost:20840/topics
  • API:
    • Input:
      • text: UTF-8 encoded text (max. 32MB)
      • lan (optional but recommended): 2 letter abbreviation (ISO ..) of the language ('en' = default)
      • key (optional): must be provided if apiKeyRequired is enabled on server side
    • Output:
      • topics: key/value pairs where value is the topic, and value normalized (0..1) value
        • _stats contains the absolute occurances (not normalized)
Examples 

% curl -H "Content-Type: application/json" -F key=yourAPIKey \
       -F [email protected] http://localhost:20840/topics
{
   "topics": {
      "Asia" : 0.2,
      "China" : 0.2,
      "Earth" : 0.6,
      "Europe" : 1,
      "Germany" : 0.2,
      "Italy" : 0.4,
      "Linux" : 0.2,
      "Switzerland" : 0.2,
      "UNIX" : 0.2,
      "Ubuntu" : 0.2,
      "United Kingdom" : 0.2,
      "art" : 0.4,
      "astronomy" : 0.2,
      "commerce" : 0.4,
      "computer" : 0.2,
      "cosmology" : 0.2,
      "entertainment" : 0.2,
      "geography" : 0.6,
      "literature" : 0.2,
      "media" : 0.6,
      "movies" : 0.6,
      "music" : 0.2,
      "operating systems" : 0.1,
      "science" : 0.5,
      "software" : 0.2,
      "technology" : 0.2,
      "time" : 0.06
      "_stats" : {
         "Asia" : 1,
         "China" : 1,
         "Earth" : 3,
         "Europe" : 5,
         "Germany" : 1,
         "Italy" : 2,
         "Linux" : 1,
         "Switzerland" : 1,
         "UNIX" : 1,
         "Ubuntu" : 1,
         "United Kingdom" : 1,
         "_all" : 190,
         "_match" : 21,
         "art" : 2,
         "astronomy" : 1,
         "commerce" : 2,
         "computer" : 1,
         "cosmology" : 1,
         "entertainment" : 1,
         "geography" : 3,
         "literature" : 1,
         "media" : 3,
         "movies" : 3,
         "music" : 1,
         "operating systems" : 0.5,
         "science" : 2.5,
         "software" : 1,
         "technology" : 1,
         "time" : 0.3
      },
   },
   "server" : {
      "elapsed" : 0.587265,
      "version" : "MetaFS::Cloud 0.0.1"
   }
}

2.4. Entities

Entities (individuals, organizations, companies) extraction using MetaFS::Semantics::Entities currently.

  • Endpoint: http://localhost:20840/entities
  • API:
    • Input:
      • text: UTF-8 encoded text (max. 32MB)
      • lan (optional): 2 letter abbreviation (ISO 639) of the language ('en' = default)
      • key (optional): must be provided if apiKeyRequired is enabled on server side
    • Output:
      • entities: array of entities
        • name: full name
        • type: individual, organization, or company
        • description.value: some background information (very brief)
        • count: counter of occurance (most mentioned entity listed first)
        • birthDate: UNIX epoch (seconds since 1970/01/01: 00:00:00 UTC)
        • deathDate: UNIX epoch (seconds since 1970/01/01: 00:00:00 UTC)
Examples 

% curl -H "Content-Type: application/json" -F key=yourAPIKey \
       -F [email protected] http://localhost:20840/entities
{
  "entities": [
      {
         "_birthPlace" : {
            "id" : [
               "http://dbpedia.org/resource/%C5%8Cta,_Tokyo"
            ]
         },
         "_deathPlace" : {
            "id" : [
               "http://dbpedia.org/resource/Setagaya"
            ]
         },
         "birthDate" : -1886414400,
         "birthPlace" : "Ota, Tokyo",
         "count" : 1,
         "deathDate" : 905083200,
         "deathPlace" : "Setagaya",
         "description" : {
            "lan" : "en",
            "value" : "Japanese film director, screenwriter, producer, and editor"
         },
         "givenName" : {
            "lan" : "en",
            "value" : "Akira"
         },
         "id" : "http://dbpedia.org/resource/Akira_Kurosawa",
         "name" : "Akira Kurosawa",
         "source" : [
            "TheFamousPeople.com (2016)",
            "Ranker.com: The Most Influential People of All Time"
         ],
         "subtype" : [
            "film producer",
            "screenwriter",
            "film editor"
         ],
         "surname" : {
            "lan" : "en",
            "value" : "Kurosawa"
         },
         "type" : "individual"
      },
      ...
   ],
   "server" : {
      "elapsed" : 0.65276195,
      "version" : "MetaFS::Cloud 0.0.1"
   }
}

2.5. Music

Basic analysis of music using MetaFS::Semantics::Music (Essentia) currently.

  • Endpoint: http://localhost:20840/music
  • API:
    • Input:
      • audio: must be in MP3
      • key (optional): must be provided if apiKeyRequired is enabled on server side
    • Output:
      • lowlevel
      • rhythm
        • bpm
      • tonal
      • highlevel
        • danceability
        • gender
        • genre_* diverse genre conclusions
        • genres array of genres from different genre conclusions
        • mood_* diverse mood conclusions (acoustic, aggressive, electronic, happy, party, relaxed, sad)
        • moods array of moods
        • timbre
        • voice_instrumental
Examples 

% curl -H "Content-Type: application/json" -F key=yourAPIKey \
       -F [email protected] http://localhost:20840/music
{
   "results": {
      "lowlevel": {
         "average_loudness": 0.90785574913, 
         "barkbands": {
            ...
         },
         "barkbands_crest": {
            ...
         }, 
         "barkbands_flatness_db": {
            ...
         }, 
         "barkbands_kurtosis": {
            ...
         }, 
         "barkbands_skewness": {
            ...
         }, 
         ...
      }, 
      "metadata": {
         "audio_properties": {
            "analysis_sample_rate": 44100, 
            "bit_rate": 284251, 
            "codec": "mp3", 
            "downmix": "mix", 
            "equal_loudness": 0, 
            "length": 236.946670532, 
            "lossless": 0, 
            "md5_encoded": "9cc0c278d0ad438615e4eb84a5537f5a", 
            "replay_gain": -15.0083122253, 
            "sample_rate": 44100
         }, 
         "tags": {
            "album": [
               "Thus restoring it"
            ], 
            "albumartist": [
               "Dream Youth"
            ], 
            "artist": [
               "Dream Youth"
            ], 
            "copyright": [
               "Attribution-Noncommercial-Share Alike 3.0 United States: http://creativecommons.org/licenses/by-nc-sa/3.0/us/"
            ], 
            "date": [
               "2015-01-22 12:11:54", 
               "2015-01-22 12:11:54"
            ], 
            "file_name": "semantics-audio-26104.mp3", 
            "genre": [
               "Electronic"
            ], 
            "title": [
               "Endurance"
            ], 
            "tracknumber": [
               1
            ]
         }, 
         "version": {
            "essentia": "2.1-dev", 
            "essentia_git_sha": "v2.1_beta2-546-g5c457ef", 
            "extractor": "music 1.0"
         }
      }, 
      "rhythm": {
         "beats_count": 591, 
         "beats_loudness": {
            "dmean": 0.0269927792251, 
            "dmean2": 0.0491756461561, 
            "dvar": 0.000771102553699, 
            "dvar2": 0.00206472235732, 
            "max": 0.157152116299, 
            "mean": 0.0509064495564, 
            "median": 0.049879014492, 
            "min": 7.71759550844e-06, 
            "var": 0.000966897699982
         }, 
         "beats_loudness_band_ratio": {
            ...
         }, 
         "beats_position": [
            0.441179126501, 
            0.847528338432, 
            1.25387752056, 
            1.66022670269, 
            2.0549659729, 
            2.4497051239, 
            2.85605430603, 
            3.26240348816, 
            ...
            235.264572144, 
            235.670928955, 
            236.077270508, 
            236.483627319
         ], 
         "bpm": 150.061599731, 
         "bpm_histogram_first_peak_bpm": {
            "dmean": 0, 
            "dmean2": 0, 
            "dvar": 0, 
            "dvar2": 0, 
            "max": 152, 
            "mean": 152, 
            "median": 152, 
            "min": 152, 
            "var": 0
         }, 
         "bpm_histogram_first_peak_spread": {
            "dmean": 0, 
            "dmean2": 0, 
            "dvar": 0, 
            "dvar2": 0, 
            "max": 0.446153819561, 
            "mean": 0.446153819561, 
            "median": 0.446153819561, 
            "min": 0.446153819561, 
            "var": 0
         }, 
         "bpm_histogram_first_peak_weight": {
            "dmean": 0, 
            "dmean2": 0, 
            "dvar": 0, 
            "dvar2": 0, 
            "max": 0.549152553082, 
            "mean": 0.549152553082, 
            "median": 0.549152553082, 
            "min": 0.549152553082, 
            "var": 0
         }, 
         "bpm_histogram_second_peak_bpm": {
            "dmean": 0, 
            "dmean2": 0, 
            "dvar": 0, 
            "dvar2": 0, 
            "max": 144, 
            "mean": 144, 
            "median": 144, 
            "min": 144, 
            "var": 0
         }, 
         "bpm_histogram_second_peak_spread": {
            "dmean": 0, 
            "dmean2": 0, 
            "dvar": 0, 
            "dvar2": 0, 
            "max": 0, 
            "mean": 0, 
            "median": 0, 
            "min": 0, 
            "var": 0
         }, 
         "bpm_histogram_second_peak_weight": {
            "dmean": 0, 
            "dmean2": 0, 
            "dvar": 0, 
            "dvar2": 0, 
            "max": 0.00847457628697, 
            "mean": 0.00847457628697, 
            "median": 0.00847457628697, 
            "min": 0.00847457628697, 
            "var": 0
         }, 
         "danceability": 1.14444255829, 
         "onset_rate": 4.35939216614
      }, 
      "tonal": {
         "chords_changes_rate": 0.0425156727433, 
         "chords_histogram": [
            52.3510971069, 
            5.60344839096, 
            4.4866771698, 
            9.97257041931, 
            0.0783699080348, 
            1.86128520966, 
            0, 
            8.83620643616, 
            0, 
            1.13636362553, 
            0, 
            0, 
            0, 
            0, 
            0, 
            0, 
            0, 
            0, 
            0, 
            0, 
            0.0391849540174, 
            0, 
            12.049372673, 
            3.58542323112
         ], 
         "chords_key": "G", 
         "chords_number_rate": 0.00176332285628, 
         "chords_scale": "minor", 
         "chords_strength": {
            "dmean": 0.00801159814, 
            "dmean2": 0.00709551991895, 
            "dvar": 4.51187661383e-05, 
            "dvar2": 4.57736095996e-05, 
            "max": 0.727361500263, 
            "mean": 0.523131847382, 
            "median": 0.532216072083, 
            "min": 0.277241885662, 
            "var": 0.00745408656076
         }, 
         "hpcp": {
            ...
         }, 
         "hpcp_entropy": {
            "dmean": 0.605283677578, 
            "dmean2": 1.01456737518, 
            "dvar": 0.309801846743, 
            "dvar2": 0.742707848549, 
            "max": 4.44419336319, 
            "mean": 1.81851243973, 
            "median": 1.76298832893, 
            "min": 0, 
            "var": 0.538233816624
         }, 
         "key_key": "G", 
         "key_scale": "minor", 
         "key_strength": 0.722897529602, 
         "thpcp": [
            1, 
            0.598947942257, 
            0.178362175822, 
            0.1271520257, 
            0.125145673752, 
            0.198196232319, 
            0.274295479059, 
            0.227354869246, 
            0.245102033019, 
            0.364173471928, 
            0.271588206291, 
            0.102842338383, 
            0.0678262114525, 
            0.0740041807294, 
            0.233938544989, 
            0.397917747498, 
            0.252047985792, 
            0.0752510279417, 
            0.0569287799299, 
            0.068927206099, 
            0.272214263678, 
            0.575084328651, 
            0.444376915693, 
            0.246237516403, 
            0.271423757076, 
            0.150798872113, 
            0.0497161261737, 
            0.0508556291461, 
            0.0635204464197, 
            0.221064269543, 
            0.367165207863, 
            0.231969103217, 
            0.0800206959248, 
            0.0686402097344, 
            0.126137942076, 
            0.600395858288
         ], 
         "tuning_diatonic_strength": 0.583254814148, 
         "tuning_equal_tempered_deviation": 0.0445745699108, 
         "tuning_frequency": 439.238189697, 
         "tuning_nontempered_energy_ratio": 0.654221713543
      },
      "highlevel": {
       "danceability": {
          "all": {
             "danceable": 0.358591020107, 
             "not_danceable": 0.641408979893
          }, 
          "probability": 0.641408979893, 
          "value": "not_danceable"
       }, 
       "gender": {
          "all": {
             "female": 0.494702041149, 
             "male": 0.505297958851
          }, 
          "probability": 0.505297958851, 
          "value": "male"
       }, 
       "genre_dortmund": {
          "all": {
             "alternative": 0.00495427660644, 
             "blues": 0.000524605740793, 
             "electronic": 0.993570208549, 
             "folkcountry": 0.000506910029799, 
             "funksoulrnb": 5.5754294408e-06, 
             "jazz": 0.000220191112021, 
             "pop": 3.38310746884e-05, 
             "raphiphop": 3.93479012928e-06, 
             "rock": 0.000180469651241
          }, 
          "probability": 0.993570208549, 
          "value": "electronic"
       }, 
       "genre_electronic": {
          "all": {
             "ambient": 0.538724541664, 
             "dnb": 0.00227561686188, 
             "house": 0.18889093399, 
             "techno": 0.0173822771758, 
             "trance": 0.252726644278
          }, 
          "probability": 0.538724541664, 
          "value": "ambient"
       }, 
       "genre_rosamerica": {
          "all": {
             "classic": 0.0609021745622, 
             "dance": 0.0662312731147, 
             "hiphop": 0.0397627539933, 
             "jazz": 0.111906446517, 
             "pop": 0.124143958092, 
             "rhythm": 0.463972151279, 
             "rock": 0.0915464907885, 
             "speech": 0.0415347591043
          }, 
          "probability": 0.463972151279, 
          "value": "rhythm"
       }, 
       "genre_tzanetakis": {
          "all": {
             "blues": 0.0528554059565, 
             "classic": 0.0424292124808, 
             "country": 0.063417673111, 
             "disco": 0.0528487153351, 
             "hiphop": 0.0634207203984, 
             "jazz": 0.3171184659, 
             "metal": 0.0801980495453, 
             "pop": 0.105717591941, 
             "reggae": 0.0634287297726, 
             "rock": 0.158565431833
          }, 
          "probability": 0.3171184659, 
          "value": "jazz"
       }, 
       "genres": [
         "rhytm"
       ], 
       "ismir04_rhythm": {
          "all": {
             "ChaChaCha": 0.0278143845499, 
             "Jive": 0.00828776694834, 
             "Quickstep": 0.00265214941464, 
             "Rumba-American": 0.0768477097154, 
             "Rumba-International": 0.0184737313539, 
             "Rumba-Misc": 0.00713536841795, 
             "Samba": 0.0109753096476, 
             "Tango": 0.76195114851, 
             "VienneseWaltz": 0.0833574607968, 
             "Waltz": 0.00250495574437
          }, 
          "probability": 0.76195114851, 
          "value": "Tango"
       }, 
       "mood_acoustic": {
          "all": {
             "acoustic": 0.517694652081, 
             "not_acoustic": 0.482305377722
          }, 
          "probability": 0.517694652081, 
          "value": "acoustic"
       }, 
       "mood_aggressive": {
          "all": {
             "aggressive": 0.0224821846932, 
             "not_aggressive": 0.977517843246
          }, 
          "probability": 0.977517843246, 
          "value": "not_aggressive"
       }, 
       "mood_electronic": {
          "all": {
             "electronic": 0.895219087601, 
             "not_electronic": 0.104780934751
          }, 
          "probability": 0.895219087601, 
          "value": "electronic"
       }, 
       "mood_happy": {
          "all": {
             "happy": 0.0525550544262, 
             "not_happy": 0.947444975376
          }, 
          "probability": 0.947444975376, 
          "value": "not_happy"
       }, 
       "mood_party": {
          "all": {
             "not_party": 0.966591238976, 
             "party": 0.0334087572992
          }, 
          "probability": 0.966591238976, 
          "value": "not_party"
       }, 
       "mood_relaxed": {
          "all": {
             "not_relaxed": 0.011651433073, 
             "relaxed": 0.988348543644
          }, 
          "probability": 0.988348543644, 
          "value": "relaxed"
       }, 
       "mood_sad": {
          "all": {
             "not_sad": 0.520429193974, 
             "sad": 0.479570806026
          }, 
          "probability": 0.520429193974, 
          "value": "not_sad"
       }, 
       "moods_mirex": {
          "all": {
             "Cluster1": 0.115959979594, 
             "Cluster2": 0.131191283464, 
             "Cluster3": 0.44725304842, 
             "Cluster4": 0.147296324372, 
             "Cluster5": 0.1582993716
          }, 
          "probability": 0.44725304842, 
          "value": "Cluster3"
       },
       "moods": [
         "acoustic",
         "electronic",
         "relaxed"
       ], 
       "timbre": {
          "all": {
             "bright": 0.576756954193, 
             "dark": 0.423243045807
          }, 
          "probability": 0.576756954193, 
          "value": "bright"
       }, 
       "tonal_atonal": {
          "all": {
             "atonal": 0.214664667845, 
             "tonal": 0.785335302353
          }, 
          "probability": 0.785335302353, 
          "value": "tonal"
       }, 
       "voice_instrumental": {
          "all": {
             "instrumental": 0.988363802433, 
             "voice": 0.0116362217814
          }, 
          "probability": 0.988363802433, 
          "value": "instrumental"
       }
   },
   "server" : {
      "elapsed" : 3.872166,
      "version" : "MetaFS::Cloud 0.0.1"
   }
}

2.6. Faces

Face recognition and training using OpenFace currently.

  • Endpoint: http://localhost:20840/faces
  • API:
    • Input:
      • image: JPEG, scale image to 512 pixels width max to save bandwidth
      • key (optional): must be provided if apiKeyRequired is enabled on server side
      • train (optional): full name, e.g. "Alan Turing"
      • wikidata (optional): e.g. Q7251
      • class (optional): default global, if you like to lookup or train a subclass, name it so
    • Output:
      • individuals: object with keys of names of individuals
        • wikidata: if the face was trained with wikidata set, then it will be returned
        • position: array with floats of position of the face (x, y, width, height)
Examples 

% curl -H "Content-Type: application/json" -F key=yourAPIKey \
       -F [email protected] http://localhost:20840/faces
{
   "individuals": {
      "Alan Turing": {
         "wikidata": "Q7251",
         "position": [ 
            156,
            200,
            90,
            150
         ]
      }
   },
   "server" : {
      "elapsed" : 5.21777134,
      "version" : "MetaFS::Cloud 0.0.1"
   }
}

2.6.1. Training

If you run your own services, and enabled for all or just a particular API-key, then you can train a new or existing face.

Input:

  • train: full name
  • wikidata (optional): wikidata identifier e.g. Q7251 for Alan Turing
  • class (optional): define class to differentiate classes, default global
Note: make sure only a single face is visible of the person to train. 

% curl -H "Content-Type: application/json" -F key=yourAPIkey \
       -F '{"train":"Alan Turing","wikidata":"Q7251"}' \
       -F [email protected] http://localhost:20840/openface
{
   "individuals": {
      "Alan Turing": {
         "wikidata": "Q7251",
         "position": [ 
            67,
            30,
            260,
            352
         ]
      }
   }
}

The output is merely a confirmation plus the position of the face in the image.

An easy to use command-line interface (CLI) for OpenFace is coming soon: 

% openface test.jpg
   lookup an image for faces and their identity

% openface "--train=Alan Turing" --wikidata=Q7251 alan-turing*.jpg
   train an existing or new identity with photos (with single person in it)

% openface --commit
   process all trainings

2.7. ImageTags

Image tagging using MetaFS::Semantics::ImageTags (via DarknetNN/Image-Net currently, if another implementation is chosen at a later time the tagging classification of Image-Net is maintained).

  • Endpoint: http://localhost:20840/imagetags
  • API:
    • Input:
      • image: JPEG, scale image to 720 pixels height max to save bandwidth
      • key (optional): must be provided if apiKeyRequired is enabled on server side
    • Output:
      • tags: single english descriptive tags
Examples 

% curl -F key=yourapikey -F [email protected] http://localhost:20840/imagetags
{
   "results" : {
      "imagetags" : [
         "chain mail",
         "breastplate",
         "cuirass",
         "poncho",
         "fur coat",
         "cardigan"
      ]
   },
   "server" : {
      "elapsed" : 1.97446608543396,
      "version" : "MetaFS::Cloud 0.0.1"
   }
}

2.8. Caption

Single caption of images using MetaFS::Semantics::Caption (via NeuralTalk2 currently).

  • Endpoint: http://localhost:20840/caption
  • API:
    • Input:
      • image: JPEG, scale image to 720 pixels height max to save bandwidth
      • key (optional): must be provided if apiKeyRequired is enabled on server side
    • Output:
      • caption: single english descriptive sentence
Examples 

% curl -F key=yourapikey -F [email protected] http://localhost:20840/caption
{
   "results" : {
      "caption" : "a sheep standing on a lush green hillside"
   },
   "server" : {
      "elapsed" : 11.4574301242828,
      "version" : "MetaFS::Cloud 0.0.1"
   }
}

Perl API: 

use MetaFS::Cloud;
use MetaFS::Helper;

my $c = new MetaFS::Cloud({host=>'localhost'});
my $d = readFile("test.jpg");

my $r = $c->rpc('caption',{image=>$d});

print toJSON($r);

2.9. DenseCap

Dense or detailed caption of images using MetaFS::Semantics::DenseCaption (via DenseCap currently).

  • Endpoint: http://localhost:20840/densecap
  • API:
    • Input:
      • image: JPEG, scale image to 720 pixels height max to save bandwidth
      • key (optional): must be provided if apiKeyRequired is enabled on server side
    • Output:
      • captions: array of strings which contain the english sentences of the caption, all lowercase
      • boxes: array of boxes, a box is an array of 4 floats: x, y, width, height
      • scores: array of scores (floats) corresponding to captions array
Examples 

% curl -F key=yourapikey -F [email protected] http://localhost:20840/densecap
{
   "results": {
      "captions": [
         "a man with a beard",
         "the man is smiling",
         "a woman with a large umbrella",
         "the wall is made of wood",
         ...
      ],
      "boxes": [
         [  
            62.229705810547,
            177.2357635498,
            340.2033996582,
            208.59931945801
         ],
         [  
            361.14736938477,
            234.99795532227,
            128.89819335938,
            150.37048339844
         ],
         [  
            199.35296630859,
            1.6991653442383,
            522.61322021484,
            222.3671875
         ],
         [
            187.83885192871,
            70.982749938965,
            129.63374328613,
            175.37335205078
         ],
         ...
      ],
      "scores": [
         4.4735717773438,
         3.0758724212646,
         2.8983414173126,
         1.4877238273621,
         1.4525685310364,
         1.0493986606598,
         ...
      ],
   },
   "server" : {
      "elapsed" : 25.026593208313,
      "version" : "MetaFS::Cloud 0.0.1"
   }
}

Perl API: 

use MetaFS::Cloud;
use MetaFS::Helper;

my $c = new MetaFS::Cloud({host=>'localhost'});
my $d = readFile("test.jpg");

my $r = $c->rpc('densecap',{image=>$d});

print toJSON($r);

3. Configuration

Define the cloud facility for server (metafs-cloud) and/or client (metafs + its handlers):

/var/lib/metafs/conf/cloud.conf: 

{
   "server": {
      #  -- Note: if you enabled it, mongodb metafscloud.keys is opened to lookup 'key'
      # "apiKeyRequired": 1,           # -- 0 (default) = off, 1 = on
      
      # "access": "192.168.2.0/24",    # -- allow only 192.168.2.*
      # "access": "0.0.0.0/0",         # -- allow all
      # "access": "*",                 # -- dito
      # "port": 20840,                 # -- default port 20840
      # "ssl": 1,                      # -- 0 (default) = off, 1 = on
      
      "services": {
         "ping": { },
         "sentiments": { },
         "topics": { },
         "entities": { },
         "music": { },
         "faces": {
            # "train": {
            #    "access": "192.168.0.0/24",
            #    `apiKeyRequired`: 1, 
            # },
            # "access": "192.168.0.0/24",
            # "apiKeyRequired": 1, 
         },
         "imagenet": { },
         "caption": { },
         "densecap": { },
      }
   },
   
   "client": {
      # "host": "localhost",           # -- default host
      # "port": 20840,                 # -- default port 20840
      # "ssl": 1,                      # -- 0 (default) = off, 1 = on
      # "key": "yourapikey",
      
      "services": {
         "ping": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
         "sentiments": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
         "topics": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
         "entities": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
         "music": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
         "faces": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
         "caption": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
         "imagenet": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
         "densecap": { 
            # "host": "localhost",
            # "port": 20840
            # "key": "yourapikey",
            # "ssl": 1,
         },
      },
   }
}

4. metafs-cloud

This also means, all cloud/xyz scripts and applications have access to all MetaFS::* functionality, but require their own initialization of such.

4.1. Command Line Interface (CLI)

metafs-cloud is the server but also a simple admin tool: 
% metafs-cloud 
or
% metafs-cloud server
== MetaFS::Cloud server 0.0.5 started, port 20840

New API Key 

% metafs-cloud newkey
   new key: 2a7bd133ae9350ddfc4ca6dd241d1cd8-57432098-de67e3

List API Keys 

% metafs-cloud listkeys
   2a7bd133ae9350ddfc4ca6dd241d1cd8-57432098-de67e3 (created 2016/05/21 07:36:58.000)
      3 requests
total 1 keys
Delete API Keys 
% metafs-cloud delkey 2a7bd133ae9350ddfc4ca6dd241d1cd8-57432098-de67e3
   deleted 2a7bd133ae9350ddfc4ca6dd241d1cd8-57432098-de67e3

5. Programming Stack

◹
MetaFS::Cloud API Stack
To understand MetaFS::Cloud properly, let's use a simple example:
  1. semantics/sentiments is called as part of the semantics text feed
  2. which uses MetaFS::Semantics::Sentiments and depending
  3. on cloud.conf declaration of client.sentiments.host then a MetaFS Cloud RPC (Remote Procedure Call) is made (app: "sentiments")
  4. where on the other end metafs-cloud listens for requests, and
  5. executes or evaluates[1] cloud/sentiments, which uses a local MetaFS::Semantics::Sentiments
  6. the results are passed back finally to the semantics/sentiments
  1. if app.pl or app.js is found either as Perl or JavaScript evaluated, otherwise the program is executed

6. Programming Cloud Services

coming soon

7. Updates

Significant updates of this document: Authors