Add markdown documentation; Move python library into its own repository

Author: xinzhel97

README.md

@@ -1 +1,42 @@
-# planimation-pythonAPI
+# Access Planimation API
+
+The Planimation API provides programmatic access to Planimation, an online PDDL problem solver and visualiser. Planimation with user interface can be accessed through [here] [planimation]. A python library and a python-based command line utility are provided to easily access the API. They provide the same functionalities as the user interface.
+
+### Installation
+Simply fork this repository and you can have access to the source code. Unfortunately, there are no `pip` or `conda` installation options available at this stage.
+
+### Python Library
+
+The `planimation_api.py` library provides following methods:
+Method | Description
+------------ | -------------
+`pddl_visualise(path of domain, path of problem, path of animation, output format)` | Submit 3 pddl files which corresponds to domain, problem, animation profile respectively and receive response in one of 5 supported formats (vfg, png, gif, webm, mp4). Similar to "Build visualisation from problem" on user interface
+`vfg_visualise(path of vfg, output format)` | Submit a vfg file and receive response in one of 4 supported formats (png, gif, webm, mp4). Similar to "Build visualisation from solution VFG" on user interface
+An example of usage is demonstrated below:
+```python
+import planimation_api as api
+result = api.pddl_visualise("domain.pddl", "problem.pddl", "ap.pddl", "mp4")
+print(result) // display the name of received file
+```
+
+### Command Line Utility
+
+The `planimation.py` command-line utility provides exactly the same functionalities as the `planimation_api.py` library:
+
+`submitPDDL` submits 3 pddl files which corresponds to domain, problem, animation profile respectively and receive response in one of 5 supported formats (vfg, png, gif, webm, mp4)
+```sh
+$ planimation.py submitPDDL [path of domain] [path of problem] [path of animation profile] [output format]
+```
+`submitVFG` submits a vfg file and receive response in one of 4 supported formats (png, gif, webm, mp4)
+```sh
+$ planimation.py submitVFG  [path of VFG] [output format]                
+```
+
+### Disclaimer
+The API should be considered to be in a very alpha phase at the moment. It's not expected to handle heavy traffic and the error messages may not be complete. Until this disclaimer is removed, we **DO NOT RECOMMEND** using the API for official business (academic or otherwise).
+
+### Thanks
+The first version of Planimation API is developed by Changyuan Liu, Lingfeng Qiang, Mengyi Fan, Xinzhe Li and Zhaoqi Fang under Nir Lipovetzky's guidance.
+
+[//]: # 
+   [planimation]:<https://planimation.planning.domains/>

planimation.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+import sys,os
+import planimation_api as api
+
+USAGE_STRING = """
+No command-line options given. Usage:
+
+planimation.py submitVFG 		[absolute path of vfg file] [download option (png/webm/gif/mp4)]
+planimation.py submitPDDL 		[absolute path of domain file] [absolute path of problem file] [absolute path of animation file] [download option (vfg/png/webm/gif/mp4)]
+"""
+
+
+if __name__ == "__main__":
+	# give the usage of command line
+	if len(sys.argv) == 1:
+		print(USAGE_STRING)
+		exit(0)
+	i=1
+	while i< len(sys.argv):
+		#check submitVFG function
+		if sys.argv[i] == "submitVFG":
+			i+=1
+			if len(sys.argv) == 4:
+				vfg = sys.argv[i].strip()
+
+				if vfg.endswith('.vfg'):
+					i+=1
+					downloadtype = sys.argv[i].strip()
+					
+					if downloadtype!='png' and downloadtype!='webm' and downloadtype!='gif' and downloadtype!='mp4':
+						print("invalid download type")
+						exit(1)
+					else:
+						print(vfg)
+						print(downloadtype)
+						api.vfg_visualise(vfg,downloadtype)
+						exit(0)
+				else:
+					print("Invalid vfg file type")
+					exit(1)
+			else:
+				print("Invalid argument entered for submitVFG")
+				exit(1)
+		# check submitPlan function 		
+		elif sys.argv[i] == "submitPDDL":
+			i+=1
+			if len(sys.argv) == 6:
+				domainFile = sys.argv[i].strip()
+				i+=1
+				problemFile = sys.argv[i].strip()
+				i+=1
+				animationFile = sys.argv[i].strip()
+				if domainFile.endswith('.pddl') and problemFile.endswith('.pddl') and animationFile.endswith('.pddl'):
+					i+=1
+					downloadtype = sys.argv[i].strip()
+					if downloadtype!='png' and downloadtype!='webm' and downloadtype!='gif' and downloadtype!='mp4' and downloadtype!='vfg':
+						print("invalid download type")
+						exit(1)
+					else:
+						api.pddl_visualise(domainFile,problemFile,animationFile,downloadtype)
+						exit(0)
+
+				else:
+					print("invalid input for pddls,please check your pddl files")
+					exit(1)
+
+			else:
+				print("Invalid argument numbers entered for submitPlan")
+				exit(1)
+
+		else:
+			print("no such argument input!!!")
+			exit(1)

planimation_api.py

@@ -0,0 +1,65 @@
+import requests
+from datetime import datetime
+import re
+
+# To be changed once deployed on actural server
+pddl_url = "http://127.0.0.1:8000/upload/(?P<filename>[^/]+)$"
+vfg_url = "http://127.0.0.1:8000/downloadVisualisation"
+
+# check if the input file is in the correct format using regex
+def check_input(filename, format):
+    x = re.search("^.+\."+format+"$", filename)
+    return bool(x)
+
+
+# helper function to read file
+def read_file(filename):
+    file = open(filename, "rb")
+    content = file.read()
+    file.close()
+    return content
+
+
+# send 3 PDDL files and get back either vfg, png, gif, webm or mp4 file
+def pddl_visualise(domain_file, problem_file, animation_profile, output_format):
+    if check_input(domain_file, "pddl") is False or check_input(problem_file, "pddl") is False \
+            or check_input(animation_profile, "pddl") is False:
+        print("Error: incorrect input format; all input files should be in PDDL format")
+        return None
+    if output_format != "png" and output_format != "webm" and output_format != "gif" and output_format != "mp4" \
+            and output_format != "vfg":
+        print("Error: desired output format is not supported; only vfg, png, gif, webm and mp4 are supported")
+        return None
+    domain = read_file(domain_file)
+    problem = read_file(problem_file)
+    animation = read_file(animation_profile)
+    files = ("domain", (None, domain)), ("problem", (None, problem)), ("animation", (None, animation)), \
+            ("fileType", (None, output_format))
+    r = requests.post(pddl_url, files=files)
+    if output_format == "png":
+        output_format = "zip"
+    output_name = "planimation " + datetime.now().strftime("%Y-%m-%d_%X.") + output_format
+    with open(output_name, "wb") as output:
+        for chunk in r.iter_content(chunk_size=None):
+            output.write(chunk)
+    return output_name
+
+
+# send a vfg file and get back either png, gif, webm or mp4 file
+def vfg_visualise(vfg_file, output_format):
+    if check_input(vfg_file, "vfg") is False:
+        print("Error: incorrect input format; input should be in vfg format")
+        return None
+    if output_format != "png" and output_format != "webm" and output_format != "gif" and output_format != "mp4":
+        print("Error: desired output format is not supported; only png, gif, webm and mp4 are supported")
+        return None
+    vfg = read_file(vfg_file)
+    files = ('vfg', (None, vfg)), ('fileType', (None, output_format))
+    r = requests.post(vfg_url, files=files)
+    if output_format == "png":
+        output_format = "zip"
+    output_name = "planimation " + datetime.now().strftime("%Y-%m-%d_%X.") + output_format
+    with open(output_name, "wb") as output:
+        for chunk in r.iter_content(chunk_size=None):
+            output.write(chunk)
+    return output_name