You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Some tests require Vuforia credentials. To run these tests, add the Vuforia credentials to the file ``vuforia_secrets.env``. See “Connecting to Vuforia”.
54
+
Some tests require Vuforia credentials.
55
+
To run these tests, add the Vuforia credentials to the file ``vuforia_secrets.env``.
56
+
See “Connecting to Vuforia”.
54
57
55
58
Then run ``pytest``:
56
59
@@ -61,19 +64,26 @@ Then run ``pytest``:
61
64
Connecting to Vuforia
62
65
---------------------
63
66
64
-
To connect to Vuforia, Vuforia target databases must be created via the Vuforia Web UI. Then, secret keys must be set as environment variables.
67
+
To connect to Vuforia, Vuforia target databases must be created via the Vuforia Web UI.
68
+
Then, secret keys must be set as environment variables.
65
69
66
-
The test infrastructure allows those keys to be set in the file ``vuforia_secrets.env``. See ``vuforia_secrets.env.example`` for the environment variables to set.
70
+
The test infrastructure allows those keys to be set in the file ``vuforia_secrets.env``.
71
+
See ``vuforia_secrets.env.example`` for the environment variables to set.
67
72
68
-
Do not use a target database that you are using for other purposes. This is because the test suite adds and deletes targets.
73
+
Do not use a target database that you are using for other purposes.
74
+
This is because the test suite adds and deletes targets.
69
75
70
-
To create a target database, first create a license key in the `License Manager <https://developer.vuforia.com/targetmanager/licenseManager/licenseListing>`__. Then, add a database from the `Target Manager <https://developer.vuforia.com/targetmanager>`__.
76
+
To create a target database, first create a license key in the `License Manager <https://developer.vuforia.com/targetmanager/licenseManager/licenseListing>`__.
77
+
Then, add a database from the `Target Manager <https://developer.vuforia.com/targetmanager>`__.
71
78
72
79
To find the environment variables to set in the ``vuforia_secrets.env`` file, visit the Target Database in the Target Manager and view the “Database Access Keys”.
73
80
74
-
Two databases are necessary in order to run all the tests. One of those must be an inactive project. To create an inactive project, delete the license key associated with a database.
81
+
Two databases are necessary in order to run all the tests.
82
+
One of those must be an inactive project.
83
+
To create an inactive project, delete the license key associated with a database.
75
84
76
-
Targets sometimes get stuck at the “Processing” stage meaning that they cannot be deleted. When this happens, create a new target database to use for testing.
85
+
Targets sometimes get stuck at the “Processing” stage meaning that they cannot be deleted.
86
+
When this happens, create a new target database to use for testing.
77
87
78
88
Skipping some tests
79
89
-------------------
@@ -83,13 +93,18 @@ Set either ``SKIP_MOCK`` or ``SKIP_REAL`` to ``1`` to skip tests against the moc
83
93
Travis CI
84
94
---------
85
95
86
-
Tests are run on Travis CI. The configuration for this is in ``.travis.yml``.
96
+
Tests are run on Travis CI.
97
+
The configuration for this is in ``.travis.yml``.
87
98
88
-
Travis CI is set up with secrets for connecting to Vuforia. These variables include those from ``vuforia_secrets.env.example``.
99
+
Travis CI is set up with secrets for connecting to Vuforia.
100
+
These variables include those from ``vuforia_secrets.env.example``.
89
101
90
102
To avoid hitting request quotas and to avoid conflicts when running multiple tests in prallel, we use multiple target databases.
91
103
92
-
Travis builds use a different credentials file depending on the build number. For example, build 2045.1 will use a different credentials file to build 2045.2. This should avoid conflicts, but in theory the same credentials file may be run across two Pull Request builds. This may cause errors.
104
+
Travis builds use a different credentials file depending on the build number.
105
+
For example, build 2045.1 will use a different credentials file to build 2045.2.
106
+
This should avoid conflicts, but in theory the same credentials file may be run across two Pull Request builds.
107
+
This may cause errors.
93
108
94
109
How to set Travis CI secrets
95
110
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -103,7 +118,9 @@ Create environment variable files for secrets:
Add Vuforia credentials for different target databases to the new files in the ``ci_secrets/`` directory. Add as many credentials files as there are builds in the Travis matrix. All credentials files can share the same credentials for an inactive database.
121
+
Add Vuforia credentials for different target databases to the new files in the ``ci_secrets/`` directory.
122
+
Add as many credentials files as there are builds in the Travis matrix.
123
+
All credentials files can share the same credentials for an inactive database.
107
124
108
125
Install the Travis CLI:
109
126
@@ -122,7 +139,9 @@ Note that the `Travis CI documentation <https://docs.travis-ci.com/user/encrypti
122
139
Travis CI Settings
123
140
~~~~~~~~~~~~~~~~~~
124
141
125
-
All targets are deleted from the database between each test. Therefore there may be conflicts if the test suite is run concurrently as Travis CI is configured to connect to one Vuforia database. As such, Travis CI is configured not to run multiple instances of the test suite concurrently.
142
+
All targets are deleted from the database between each test.
143
+
Therefore there may be conflicts if the test suite is run concurrently as Travis CI is configured to connect to one Vuforia database.
144
+
As such, Travis CI is configured not to run multiple instances of the test suite concurrently.
126
145
127
146
Learnings about VWS
128
147
-------------------
@@ -131,7 +150,8 @@ Vuforia Web Services, at the time of writing, does not behave exactly as documen
131
150
132
151
The following list includes details of differences between VWS and expected or documented behaviour.
133
152
134
-
When attempting to delete a target immediately after creating it, a ``FORBIDDEN`` response is returned. This is because the target goes into a processing state.
153
+
When attempting to delete a target immediately after creating it, a ``FORBIDDEN`` response is returned.
154
+
This is because the target goes into a processing state.
135
155
136
156
``image`` is required for ``POST /targets``, but it is documented as not mandatory.
137
157
@@ -141,13 +161,18 @@ The database summary from ``GET /summary`` has multiple undocumented return fiel
141
161
142
162
The database summary from ``GET /summary`` has is not immediately accurate.
143
163
144
-
Some of the `Vuforia Web Services documentation <https://library.vuforia.com/articles/Training/Image-Target-Guide>`__ states that “The size of the input images must 2 MB or less”. However, other `Vuforia Web Services documentation <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ is more accurate: “Maximum image size: 2.1 MPixel. 512 KiB for JPEG, 2MiB for PNG”.
164
+
Some of the `Vuforia Web Services documentation <https://library.vuforia.com/articles/Training/Image-Target-Guide>`__ states that “The size of the input images must 2 MB or less”.
165
+
However, other `Vuforia Web Services documentation <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ is more accurate: “Maximum image size: 2.1 MPixel.
166
+
512 KiB for JPEG, 2MiB for PNG”.
145
167
146
-
The documentation page `How To Perform an Image Recognition Query <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ states that the ``Content-Type`` header must be set to ``multipart/form-data``. However, it must be set to ``multipart/form-data; boundary=<BOUNDARY>`` where ``<BOUNDARY>`` is the boundary used when encoding the form data.
168
+
The documentation page `How To Perform an Image Recognition Query <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ states that the ``Content-Type`` header must be set to ``multipart/form-data``.
169
+
However, it must be set to ``multipart/form-data; boundary=<BOUNDARY>`` where ``<BOUNDARY>`` is the boundary used when encoding the form data.
147
170
148
-
The documentation page `How To Perform an Image Recognition Query <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ states that ``Content-Type`` with be the only response header. This is not the case.
171
+
The documentation page `How To Perform an Image Recognition Query <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ states that ``Content-Type`` with be the only response header.
172
+
This is not the case.
149
173
150
174
Performing a release
151
175
--------------------
152
176
153
-
There is currently no release process. See `this issue <https://github.com/adamtheturtle/vws-python/issues/55>`__ for details.
177
+
There is currently no release process.
178
+
See `this issue <https://github.com/adamtheturtle/vws-python/issues/55>`__ for details.
This requires Python 3.6+. Get in touch with ``adamdangoor@gmail.com`` if you would like to use this with another language.
24
+
This requires Python 3.6+.
25
+
Get in touch with ``adamdangoor@gmail.com`` if you would like to use this with another language.
25
26
26
27
Mocking Vuforia
27
28
---------------
28
29
29
-
Requests made to Vuforia can be mocked. Using the mock redirects requests to Vuforia made with ``requests`` to an in-memory implementation.
30
+
Requests made to Vuforia can be mocked.
31
+
Using the mock redirects requests to Vuforia made with ``requests`` to an in-memory implementation.
30
32
31
33
.. code:: python
32
34
@@ -60,7 +62,8 @@ For example:
60
62
Authentication
61
63
~~~~~~~~~~~~~~
62
64
63
-
Connecting to the Vuforia Web Services requires an access key and a secret key. The mock also requires these keys as it provides realistic authentication support.
65
+
Connecting to the Vuforia Web Services requires an access key and a secret key.
66
+
The mock also requires these keys as it provides realistic authentication support.
64
67
65
68
By default, the mock uses random strings as the access and secret keys.
66
69
@@ -81,17 +84,20 @@ To set custom keys, set any of the following parameters in the context manager
81
84
- ``client_access_key``
82
85
- ``client_secret_key``
83
86
84
-
The mock does not check whether the access and secret keys are valid. It only checks whether the keys used to set up the mock instance match those used to create requests.
87
+
The mock does not check whether the access and secret keys are valid.
88
+
It only checks whether the keys used to set up the mock instance match those used to create requests.
85
89
86
90
Setting the database name
87
91
~~~~~~~~~~~~~~~~~~~~~~~~~
88
92
89
-
This can be done with the ``database_name`` parameter. By default this is a random string.
93
+
This can be done with the ``database_name`` parameter.
94
+
By default this is a random string.
90
95
91
96
Mocking error states
92
97
~~~~~~~~~~~~~~~~~~~~
93
98
94
-
Sometimes Vuforia is in an error state, where requests don’t work. You may want your application to handle these states gracefully, and so it is possible to make the mock emulate these states.
99
+
Sometimes Vuforia is in an error state, where requests don’t work.
100
+
You may want your application to handle these states gracefully, and so it is possible to make the mock emulate these states.
95
101
96
102
To change the state, use the ``state`` parameter when calling the mock.
97
103
@@ -106,38 +112,55 @@ To change the state, use the ``state`` parameter when calling the mock.
106
112
107
113
The states available in ``States`` are:
108
114
109
-
- ``WORKING``. This is the default state of the mock.
110
-
- ``PROJECT_INACTIVE``. This happens when the license key has been deleted.
115
+
- ``WORKING``.
116
+
This is the default state of the mock.
117
+
- ``PROJECT_INACTIVE``.
118
+
This happens when the license key has been deleted.
111
119
112
-
The mock is tested against the real Vuforia Web Services. This ensures that the implemented features of the mock behave, at least to some extent, like the real Vuforia Web Services. However, the mocks of these error states are based on observations as they cannot be reliably reproduced.
120
+
The mock is tested against the real Vuforia Web Services.
121
+
This ensures that the implemented features of the mock behave, at least to some extent, like the real Vuforia Web Services.
122
+
However, the mocks of these error states are based on observations as they cannot be reliably reproduced.
113
123
114
124
Processing time
115
125
~~~~~~~~~~~~~~~
116
126
117
-
Vuforia Web Services processes targets for varying lengths of time. The mock, by default, processes targets for half a second. To change the processing time, use the ``processing_time_seconds`` parameter.
127
+
Vuforia Web Services processes targets for varying lengths of time.
128
+
The mock, by default, processes targets for half a second.
129
+
To change the processing time, use the ``processing_time_seconds`` parameter.
118
130
119
131
Differences between the mock and the real Vuforia Web Services
The mock attempts to be realistic, but it was built without access to the source code of the original API. Please report any issues `here <https://github.com/adamtheturtle/vws-python/issues>`__. There is no attempt to make the image matching realistic.
134
+
The mock attempts to be realistic, but it was built without access to the source code of the original API.
135
+
Please report any issues `here <https://github.com/adamtheturtle/vws-python/issues>`__.
136
+
There is no attempt to make the image matching realistic.
123
137
124
138
Speed and summary accuracy
125
139
~~~~~~~~~~~~~~~~~~~~~~~~~~
126
140
127
141
The mock responds much more quickly than the real Vuforia Web Services.
128
142
129
-
Targets in the mock are set to ‘processing’ for half a second by default. This is customisable, with the ``processing_time_seconds`` parameter. In the real Vuforia Web Services, the processing stage takes varying lengths of time.
143
+
Targets in the mock are set to ‘processing’ for half a second by default.
144
+
This is customisable, with the ``processing_time_seconds`` parameter.
145
+
In the real Vuforia Web Services, the processing stage takes varying lengths of time.
130
146
131
-
The database summary in the real Vuforia Web Services takes some time to account for images. Sometimes the real summary skips image states such as the processing state. The mock is accurate immediately.
147
+
The database summary in the real Vuforia Web Services takes some time to account for images.
148
+
Sometimes the real summary skips image states such as the processing state.
149
+
The mock is accurate immediately.
132
150
133
151
Image quality and ratings
134
152
~~~~~~~~~~~~~~~~~~~~~~~~~
135
153
136
-
Targets are assigned a rating between 0 and 5 of how good they are for tracking purposes. In the mock this is a random number between 0 and 5.
154
+
Targets are assigned a rating between 0 and 5 of how good they are for tracking purposes.
155
+
In the mock this is a random number between 0 and 5.
137
156
138
-
Image targets which are not suited to detection are given ‘failed’ statuses. The criteria for these images is not defined by the Vuforia documentation. The mock is more forgiving than the real Vuforia Web Services. Therefore, an image given a ‘success’ status by the mock may not be given a ‘success’ status by the real Vuforia Web Services.
157
+
Image targets which are not suited to detection are given ‘failed’ statuses.
158
+
The criteria for these images is not defined by the Vuforia documentation.
159
+
The mock is more forgiving than the real Vuforia Web Services.
160
+
Therefore, an image given a ‘success’ status by the mock may not be given a ‘success’ status by the real Vuforia Web Services.
139
161
140
-
When updating an image for a target on the real Vuforia Web Services, the rating may stay the same. The mock changes the rating for a target to a different random number when the image is changed.
162
+
When updating an image for a target on the real Vuforia Web Services, the rating may stay the same.
163
+
The mock changes the rating for a target to a different random number when the image is changed.
0 commit comments