A utility toolkit to help develop algorithms suitable for ARgorithm
Project description
ARgorithm
Work in Progress
The ARgorithm project provides an interface to render your algorithms and data structures in augmented reality. The ARgorithmToolkit package offers packages and a command line interface needed to make and submit algorithms for the following.
How does it work ?
The Toolkit package is for developers who want to transport their own algorithms into augmented reality. The toolkit provides you with a template library which works just like your usual template library except this one records states . Each state is an event that occurs in your data structure and by keeping track of the states of your variables , data structures etc we then render them in augmented reality.
Getting started
You can install the ARgorithmToolkit using pip
pip install ARgorithmToolkit
or you can clone the repo
git clone https://github.com/ARgorithm/Toolkit.git
cd Toolkit
make init
After that you can get started with your own ARgorithm
python -m ARgorithmToolkit init
This will generate your .py
file and your .config.json
file.
- The
<name>.py
file will store your code that you will submit to the server hosting all ARgorithms - The
<name>.config.json
stores important details about your ARgorithm such as its purpose and parameters required
The <name>.py
file initially looks like this
import ARgorithmToolkit
def run(**kwargs):
stateset = ARgorithmToolkit.StateSet()
#
# Your code
#
return
You can add whatever code you want to this file using all the tools and classes present in ARgorithmToolkit but be sure to
- Your file should have one function which takes
**kwargs
input (refer here to know more about kwargs) that will should perform whatever you desire and should return the stateset. You can check out later in the document on how to use this stateset - you can create classes and additional functions in your code. Support for importing external modules is not yet added so its advisable not to add those.
the <name>.config.json
file is a JSON file storing all the metadata
{
"argorithmID" : "<name>",
"file" : "<name>.py",
"function" : "<function to be called>",
"parameters" : {
"variable-name" : "<data-type>"
} ,
"default" : {
"variable-name" : "<value>"
},
"description" : "Tell us about your ARgorithm"
}
Key | Description |
---|---|
argorithmID | name of your ARgorithm , this is generally pre filled from when you run the init command. The name of your code file should be name.py and the config should be name.config.json. [will be fixed later] |
file | The file containing your codefile |
function | The function that is going to be called |
parameters | the parameters that your ARgorithm would need, this helps in anyone using your ARgorithm to understand what is the input format |
default | default parameters in case no parameters are passed |
description | The description of ARgorithm. Helpful to people using your ARgorithm as well as other developers |
You can check out ARgorithm examples in our Github Repo
Once you are done , you can submit to server by running
python -m ARgorithmToolkit submit
or
python -m ARgorithmToolkit submit --name <name>
you can test your ARgorithm submission by using
python -m ARgorithmToolkit test
you can delete your ARgorithm submission by using
python -m ARgorithmToolkit delete
if running server image on local machine , add -l or --local flag in the submit
,delete
and test
commands . To run the server locally , pull the docker image alanjohn/argorithm-server:latest
and run it. Check out server repo here
Using ARgorithmToolkit
ARgorithmToolkit adds a few extra steps when it comes to initializing instances whose states you want to record but thats because a lot of data has to be maintained in order for smooth transitions
>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> x = ARgorithmToolkit.Variable('x',algo,0,comments='Our first variable')
>>> x.value
0
>>> x.value += 10
>>> x.value
10
>>> print(algo)
{'state_type': 'variable_declare', 'state_def': {'variable_name': 'x', 'value': 0}, 'comments': 'Our first variable'}
{'state_type': 'variable_highlight', 'state_def': {'variable_name': 'x', 'value': 10}, 'comments': ''}
As ARgorithm is tool for creating visual demonstration , you can add comments parameter to most functions. These comments get included in states and get featured as text when that state is rendered in AR.
Make sure you make the objects you want to keep track of as part of the same stateset. Each object is instantiated with a name this is important to identify arrays when rendering them
You can refer the docs and samples in the repo to understand more clearly.
StateSet
The core class to all algorithm and data structures in ARgorithmToolkit You will always need to declare this and use this when using different ARgorithmToolkit features. This is where the states are stored that later get rendered to ARgorithm App. So obviously all your ARgorithms are supposed to return this
You wont have it to interact with it much other than while initialising objects and returning results.
It has a add_comment
method that allows you to create blank states carrying description in the form of comments that you might want to show to the client while the ARgorithm is being rendered. This will prove handy when creating good demonstrations
>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> algo.add_comment("Hello world")
>>> print(algo)
{'state_type': 'comment', 'state_def': None, 'comments': 'Hello world'}
Priority Queue
ARgorithmToolkit.PriorityQueue
Methods Supported
Method | Parameters | Description | example |
---|---|---|---|
Peek | returns first element of priority queue | pq.peek() | |
Poll | pops and returns first element of priority queue | pq.poll() | |
Offer | element : any |
add element to priority queue | pq.offer(elem) |
Empty | returns boolean indicating whether queue is empty or not | pq.empty() |
Example
>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> pq = ARgorithmToolkit.PriorityQueue('pq',algo,comments="declaring priority queue")
>>> pq.offer(9)
>>> pq.offer(3)
>>> pq.offer(7)
>>> len(pq)
3
>>> pq.peek("peeking the queue")
3
>>> pq.poll()
3
>>> len(pq)
2
>>> pq.peek()
7
>>> pq.empty()
False
vectors
ARgorithmToolkit.vector
Methods supported :
Method | Parameters | Description | example |
---|---|---|---|
indexing | index : int |
accessing a certain index of vector | arr[0] |
slicing | slice:slice |
accessing a sub vector of vector | arr[1:4] |
insert | value:any index: int (optional) |
inserting a element at an index or if no index specified default last | arr.insert(10) ; arr.insert(10,2) |
remove | value:any (optional)index: int (optional) |
removing a particular value or from a particular index. Specify only one of the two | arr.remove(value=10) arr.remove(index=8) |
compare | index1 : int index2 : int func : function (optional) |
compares the values at the two indexes. returns result of == if func not specified | arr.compare(1,2) |
swap | index1 : int index2 : int |
swaps the values at the two indexes | arr.swap(2,3) |
Example
>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> vector = ARgorithmToolkit.Vector('arr' , algo)
>>> print(vector)
[]
>>> vector.insert(12)
>>> vector.insert(11,0,comments="lets insert a number at index 0")
>> vector[0]
11
>>> for x in vector:
... print(x)
...
11
12
>>> print(algo)
{'state_type': 'vector_declare', 'state_def': {'variable_name': 'arr', 'body': [12]}, 'comments': ''}
{'state_type': 'vector_insert', 'state_def': {'variable_name': 'arr', 'body': [12], 'element': 12, 'index': 1}, 'comments': ''}
{'state_type': 'vector_insert', 'state_def': {'variable_name': 'arr', 'body': [11, 12], 'element': 11, 'index': 0}, 'comments': 'lets insert a number at index 0'}
{'state_type': 'vector_iter', 'state_def': {'variable_name': 'arr', 'body': [11, 12], 'index': 0}, 'comments': ''}
{'state_type': 'vector_iter', 'state_def': {'variable_name': 'arr', 'body': [11, 12], 'index': 0}, 'comments': ''}
{'state_type': 'vector_iter', 'state_def': {'variable_name': 'arr', 'body': [11, 12], 'index': 1}, 'comments': ''}
Queue
ARgorithmToolkit.Queue
Methods supported
method | parameter | description | example |
---|---|---|---|
push | value:int |
pushes to back of queue | q.push(1) |
pop | pops from front of queue | q.pop() | |
front | displays the front of queue | q.front() | |
back | displays the back of queue | q.back() | |
empty | boolean value that indicates whether queue is empty | q.empty() |
Example
>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> queue = ARgorithmToolkit.Queue('qu',algo)
>>> queue.push(1)
>>> queue.push(2)
>>> queue.front()
1
>>> queue.pop()
1
>>> len(queue)
1
>>> while not queue.empty():
... queue.pop()
...
2
>>> print(algo)
{'state_type': 'queue_declare', 'state_def': {'variable_name': 'qu', 'body': []}, 'comments': ''}
{'state_type': 'queue_push', 'state_def': {'variable_name': 'qu', 'body': [1], 'element': 1}, 'comments': ''}
{'state_type': 'queue_push', 'state_def': {'variable_name': 'qu', 'body': [1, 2], 'element': 2}, 'comments': ''}
{'state_type': 'queue_front', 'state_def': {'variable_name': 'qu', 'body': [1, 2]}, 'comments': ''}
{'state_type': 'queue_pop', 'state_def': {'variable_name': 'qu', 'body': [2]}, 'comments': ''}
{'state_type': 'queue_pop', 'state_def': {'variable_name': 'qu', 'body': []}, 'comments': ''}
Arrays
ArgorithmToolkit.Array
Methods supported
Method | Parameter | Description | example |
---|---|---|---|
initialise | data:list , shape:tuple , dtype: int , fill:dtype |
The array can be initialised using a preexisting list or can use shape that has to be filled, we also offer choice of dtype and fill. Data is prefered over shape. Fill only works if shape is provided | Array("arr2",algo,shape=(3,4)) |
indexing | index:index |
The array generates states whenever a element is read or set in the array | arr[1,1] = 8 |
swap | index1:index , index2:index |
Swaps two elements in an array | arr.swap((0,1),(2,0)) |
compare | index1:index , index2:index , func:function |
compares the elements at the indexes using the function provided else send difference | arr.compare((0,1),(2,0)) |
:warning: Please prefer using arr[i,j]
over arr[i][j]
as the latter can cause discrepancies
Example
>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> arr = ARgorithmToolkit.Array("arr",algo,data=[[1,2],[3,4],[4,5]],comments="shape_declare")
>>> print(arr)
[[1 2]
[3 4]
[4 5]]
>>> arr[0,0]
1
>>> arr[1,1] = 8
>>> print(arr)
[[1 2]
[3 8]
[4 5]]
>>> arr.swap((0,1),(2,0))
>>> print(arr)
[[1 4]
[3 8]
[2 5]]
>>> for i in range(2):
... for j in range(2):
... print(arr[i,j])
...
1
4
3
8
>>> arr = ARgorithmToolkit.Array("arr2",algo,shape=(3,4),comments="shape_declare")
>>> print(arr)
[[0 0 0 0]
[0 0 0 0]
[0 0 0 0]]
>>> arr = ARgorithmToolkit.Array("arr2",algo,shape=(3,4),fill=3,comments="shape_declare")
>>> print(arr)
[[3 3 3 3]
[3 3 3 3]
[3 3 3 3]]
>>> print(algo)
{'state_type': 'array_declare', 'state_def': {'variable_name': 'arr', 'body': [[1, 2], [3, 4], [4, 5]]}, 'comments': 'shape_declare'}
{'state_type': 'array_iter', 'state_def': {'variable_name': 'arr', 'body': [[1, 2], [3, 4], [4, 5]], 'index': (0, 0)}, 'comments': ''}
{'state_type': 'array_iter', 'state_def': {'variable_name': 'arr', 'body': [[1, 2], [3, 8], [4, 5]], 'index': (1, 1)}, 'comments': 'Writing 8 at index (1, 1)'}
{'state_type': 'array_swap', 'state_def': {'variable_name': 'arr', 'body': [[1, 4], [3, 8], [2, 5]], 'index1': (0, 1), 'index2': (2, 0)}, 'comments': ''}
{'state_type': 'array_iter', 'state_def': {'variable_name': 'arr', 'body': [[1, 4], [3, 8], [2, 5]], 'index': (0, 0)}, 'comments': ''}
{'state_type': 'array_iter', 'state_def': {'variable_name': 'arr', 'body': [[1, 4], [3, 8], [2, 5]], 'index': (0, 1)}, 'comments': ''}
{'state_type': 'array_iter', 'state_def': {'variable_name': 'arr', 'body': [[1, 4], [3, 8], [2, 5]], 'index': (1, 0)}, 'comments': ''}
{'state_type': 'array_iter', 'state_def': {'variable_name': 'arr', 'body': [[1, 4], [3, 8], [2, 5]], 'index': (1, 1)}, 'comments': ''}
{'state_type': 'array_declare', 'state_def': {'variable_name': 'arr2', 'body': [[0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]]}, 'comments': 'shape_declare'}
{'state_type': 'array_declare', 'state_def': {'variable_name': 'arr2', 'body': [[3, 3, 3, 3], [3, 3, 3, 3], [3, 3, 3, 3]]}, 'comments': 'shape_declare'}
Stack
ARgorithmToolkit.Stack
Methods supported
method | parameter | description | example |
---|---|---|---|
push | value:int |
pushes to top of stack | q.push(1) |
pop | pops from top of stack | q.pop() | |
top | displays the top of stack | q.top() | |
empty | boolean value that indicates whether stack is empty | q.empty() |
Example
>>> import ARgorithmToolkit
>>> algo = ARgorithmToolkit.StateSet()
>>> stack = ARgorithmToolkit.Stack('st',algo)
>>> stack.push(1)
>>> stack.push(2)
>>> stack.top()
2
>>> stack.pop()
2
>>> len(stack)
1
>>> while not stack.empty():
... stack.pop()
...
1
>>> print(algo)
{'state_type': 'stack_declare', 'state_def': {'variable_name': 'st', 'body': []}, 'comments': ''}
{'state_type': 'stack_push', 'state_def': {'variable_name': 'st', 'body': [1], 'element': 1}, 'comments': ''}
{'state_type': 'stack_push', 'state_def': {'variable_name': 'st', 'body': [1, 2], 'element': 2}, 'comments': ''}
{'state_type': 'stack_top', 'state_def': {'variable_name': 'st', 'body': [1, 2]}, 'comments': ''}
{'state_type': 'stack_pop', 'state_def': {'variable_name': 'st', 'body': [1]}, 'comments': ''}
{'state_type': 'stack_pop', 'state_def': {'variable_name': 'st', 'body': []}, 'comments': ''}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ARgorithmToolkit-0.0.8-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 06479bc5a1bd07b0e1d23c892e45532df3343b36386664483bae574d0e6bf835 |
|
MD5 | 4c422178dc85e17b0394d18cac568b01 |
|
BLAKE2b-256 | 277ecd58e59e96bd1328ae902e4d9f1a2ab96e5feaeb7e1dc8eec323af49f007 |