Changes for the 1.0 SDK release (for the 2.0 app) (anki#145)

Added built-in 3D viewer / visualization support to SDK
Add 3D assets (OBJ models, MTL materials and JPG textures) for Cozmo and the 3 cubes, along with a license file.
Assets are packaged as part of the core SDK.
Added opengl class and run methods for providing a 3d visualizer for Cozmo includes:
Keyboard input to drive Cozmo via remote control
Displays navigation map, cubes, faces and custom objects in the world.
Added minimal example program to demonstrate 3d viewer usage.
Bumped min-clad version to 2.0
Lift position can now be queried as a ratio or angle (as well as existing height in distance)
pickup_furthest example now uses camera viewer by default, to match comments in the program
Update SDK versioning to "Production/Stable" from Beta (and updated all docs and images related to this)
Add support for optionally changing the resample mode when scaling images for annotation, can override default nearest-neighbor scaling with (more expensive, but smoother) bilinear filtering.
All "get_in_position" methods now move head and lift in parallel, not sequentially
Change default duration scalar for SayText action - changes to the underlying system mean that a sensible default speed is now 1.0 (not 1.8)
Add private, unused, undocumented ObstacleProx entry for nav memory map.
Fix typos in robot property doc strings.
Add optional variable to set_head_angle to allow warnings on head angle clamping to be suppressed. Used in color_finder.py which was triggering the warning a fair bit.
Add prints to 08_animation.py to make it clearer when each animation plays
Change stack_or_roll to just print the number of cubes
Changed dock + roll cube examples to output the action result, and make it clearer when it was done searching for a cube
Updated quiz questions to use digits (instead of words) for numbers as new TTS system reads them reliably.

Makefile

@@ -1,6 +1,7 @@
-.PHONY: copy-clad dist examples license wheel vagrant
+.PHONY: copy-clad dist examples license wheel vagrant installer
 
 version = $(shell perl -ne '/__version__ = "([^"]+)/ && print $$1;' src/cozmo/version.py)
+cladversion = $(shell perl -ne '/__version__ = "([^"]+)/ && print $$1;' ../cozmoclad/src/cozmoclad/__init__.py)
 
 copy-clad:
 	rm -rf src/cozmo/_internal/clad/*
@@ -64,3 +65,19 @@ dist/vagrant_bundle.zip: dist/vagrant_bundle.tar.gz
 vagrant: dist/vagrant_bundle.tar.gz dist/vagrant_bundle.zip
 
 dist: $(sdist_filename) $(wheel_filename) examples vagrant
+
+clad_wheel_filename = dist/cozmoclad-$(cladversion)-py3-none-any.whl
+$(clad_wheel_filename):
+	make -C ../cozmoclad dist
+	cp ../cozmoclad/$(clad_wheel_filename) $(clad_wheel_filename)
+
+installer_filename = sdk_installer_$(version)_clad_$(cladversion)
+installer: $(wheel_filename) $(clad_wheel_filename)
+	mkdir -p dist/
+	mkdir -p dist/$(installer_filename)
+	$(shell echo "#!/bin/bash\n\nworking_dir=\"\`dirname \\\"\$$0\\\"\`\"\n\npip3 uninstall -y cozmoclad\npip3 uninstall -y cozmo\npip3 install \"\$$working_dir/$(clad_wheel_filename)\"\npip3 install \"\$$working_dir/$(wheel_filename)\"" > dist/install.sh)
+	tar -c $(wheel_filename) $(clad_wheel_filename) | tar -C dist/$(installer_filename) -xv
+	mv dist/install.sh dist/$(installer_filename)/install
+	chmod +x dist/$(installer_filename)/install
+	cd dist && zip -r $(installer_filename).zip $(installer_filename)
+	rm -rf dist/$(installer_filename)

docs/source/.gitignore

@@ -0,0 +1 @@
+generated/

docs/source/api.rst

@@ -20,6 +20,7 @@ The API
     cozmo.nav_memory_map
     cozmo.objects
     cozmo.oled_face
+    cozmo.opengl
     cozmo.pets
     cozmo.robot
     cozmo.robot_alignment

docs/source/downloads.rst

@@ -2,8 +2,6 @@
 Downloads
 #########
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
-
 ------------
 SDK Examples
 ------------

docs/source/getstarted.rst

@@ -2,8 +2,6 @@
 Getting Started With the Cozmo SDK
 ==================================
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
-
 To make sure you get the best experience possible out of the SDK, please ensure you have followed the steps in the :doc:`Initial Setup </initial>`.
 
 ----------------

docs/source/index.rst

@@ -5,11 +5,11 @@
 
 .. image:: images/cozmo-sdk-img.jpg
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
+|
 
-==============================
-Welcome to the Cozmo SDK Beta!
-==============================
+=========================
+Welcome to the Cozmo SDK!
+=========================
 
 .. toctree::
     :maxdepth: 1

docs/source/initial.rst

@@ -4,8 +4,6 @@
 Initial Setup
 #############
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
-
 To use the Cozmo SDK, the Cozmo mobile app must be installed on your mobile device and that device must be tethered to a computer via USB cable.
 
 -------------

docs/source/install-linux.rst

@@ -4,8 +4,6 @@
 Installation - Linux
 ####################
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
-
 This guide provides instructions on installing the Cozmo SDK for computers running with an Ubuntu Linux operating system.
 
 .. warning:: The Cozmo SDK is tested and and supported on Ubuntu 14.04 and 16.04. Anki makes no guarantee the Cozmo SDK will work on other versions of Linux.  If you wish to try the Cozmo SDK on versions of Linux *other than* Ubuntu 14.04 or 16.04, please ensure the following dependencies are installed:

docs/source/install-macos.rst

@@ -4,8 +4,6 @@
 Installation - macOS / OS X
 ###########################
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
-
 This guide provides instructions on installing the Cozmo SDK for computers running with a macOS operating system.
 
 ^^^^^^^^^^^^^^^^^^^

docs/source/install-windows.rst

@@ -4,8 +4,6 @@
 Installation - Windows
 ######################
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
-
 This guide provides instructions on installing the Cozmo SDK for computers running with a Windows operating system.
 
 ^^^^^^^^^^^^^^^^^^^

docs/source/tutorial-advanced.rst

@@ -2,8 +2,6 @@
 Programming Cozmo - Advanced Tutorials
 ======================================
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
-
 Cozmo is designed for more than just simple move-and-speak programming. Cozmo can be integrated into many other applications through his API.
 
 If you are new to Python, `After Hours Programming <http://www.afterhoursprogramming.com/tutorial/Python/Overview/>`_ and `Codecademy <http://www.codecademy.com/tracks/python>`_ offer beginner's courses in learning Python; `Python.org's website <https://wiki.python.org/moin/BeginnersGuide/NonProgrammers>`_ offers a more comprehensive list of video and web tutorials. This tutorial assumes you have a minimal understanding of programming in general.

docs/source/vagrant.rst

@@ -4,8 +4,6 @@
 Alternate Install via Virtual Machine
 #####################################
 
-.. important:: THIS IS THE COZMO SDK BETA. The SDK is under development and is subject to change.
-
 .. important:: The installation steps on this page are intended only for people that are having difficulties installing the SDK using the main Installation Guide steps.
 
 If you have difficulties using the regular Installation Guide steps (e.g. you are using an unsupported Operating System / OS Version), then we also provide a self-contained VM (Virtual Machine) setup using Vagrant that you can install to run entirely inside VirtualBox. The steps are listed below.

examples/apps/3d_viewer.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2017 Anki, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License in the file LICENSE.txt or at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+'''3d Viewer example, with remote control.
+
+This is an example of how you can use the 3D viewer with a program, and the
+3D viewer and controls will work automatically.
+'''
+
+import asyncio
+
+import cozmo
+
+
+async def cozmo_program(robot: cozmo.robot.Robot):
+    while True:
+        await asyncio.sleep(1)
+
+
+cozmo.robot.Robot.drive_off_charger_on_connect = False
+cozmo.run_program(cozmo_program, use_3d_viewer=True, use_viewer=True)
+
+
+

examples/apps/color_finder.py

@@ -358,7 +358,7 @@ def on_finding_a_blob(self, blob_center, blob_size):
         '''
         self.robot.set_center_backpack_lights(map_color_to_light[self.color_to_find])
         if blob_size > (self.pixel_matrix.size/4):
-            self.lift_action = self.robot.set_lift_height(0.0, in_parallel = True)
+            self.lift_action = self.robot.set_lift_height(0.0, in_parallel=True)
         x, y = blob_center
         # 'fov' stands for 'field of view'. This is the angle amount
         # that Cozmo can see to the edges of his camera view.
@@ -399,18 +399,18 @@ def turn_toward_blob(self, amount_to_move_head, amount_to_rotate):
         '''
         self.abort_actions(self.tilt_head_action, self.rotate_action, self.drive_action)
         new_head_angle = self.robot.head_angle + amount_to_move_head
-        self.tilt_head_action = self.robot.set_head_angle(new_head_angle, in_parallel = True)
-        self.rotate_action = self.robot.turn_in_place(amount_to_rotate, in_parallel = True)
+        self.tilt_head_action = self.robot.set_head_angle(new_head_angle, warn_on_clamp=False, in_parallel=True)
+        self.rotate_action = self.robot.turn_in_place(amount_to_rotate, in_parallel=True)
         if self.state == FOUND_COLOR_STATE:
             self.amount_turned_recently += amount_to_move_head.abs_value + amount_to_rotate.abs_value
 
     def drive_toward_color_blob(self):
         '''Drives straight once prior actions have been cancelled.'''
         self.abort_actions(self.tilt_head_action, self.rotate_action)
         if self.should_start_new_action(self.drive_action):
-            self.drive_action = self.robot.drive_straight(distance_mm(500), speed_mmps(300), should_play_anim = False, in_parallel = True)
+            self.drive_action = self.robot.drive_straight(distance_mm(500), speed_mmps(300), should_play_anim=False, in_parallel=True)
         if self.should_start_new_action(self.lift_action):
-            self.lift_action = self.robot.set_lift_height(1.0, in_parallel = True)
+            self.lift_action = self.robot.set_lift_height(1.0, in_parallel=True)
 
     def turn_toward_last_known_blob(self):
         '''Turns toward the coordinates of the last recorded blob in memory.

examples/apps/quiz_questions.json

@@ -1,7 +1,7 @@
 [
     {
       "question": "What is 3 times 4?",
-      "answer_options": ["twelve", "nine", "fifteen", "fourteen"]
+      "answer_options": ["12", "9", "15", "14"]
     },
     {
       "question": "Which of these is not a type of penguin?",
@@ -17,6 +17,6 @@
     },
     {
       "question": "What is the 8th digit of Pi?",
-      "answer_options": ["six", "five", "two", "three"]
+      "answer_options": ["6", "5", "2", "3"]
     }
 ]

examples/apps/remote_control_cozmo.py

@@ -684,14 +684,23 @@ def handle_updateCozmo():
 def handle_cozmoImage():
     '''Called very frequently from Javascript to request the latest camera image'''
     if remote_control_cozmo:
-        image = remote_control_cozmo.cozmo.world.latest_image
-        if image:
-            if _display_debug_annotations != DEBUG_ANNOTATIONS_DISABLED:
-                image = image.annotate_image(scale=2)
+        try:
+            image = remote_control_cozmo.cozmo.world.latest_image
+            if image:
+                if _display_debug_annotations != DEBUG_ANNOTATIONS_DISABLED:
+                    image = image.annotate_image(scale=2)
+                else:
+                    image = image.raw_image
+
+                return flask_helpers.serve_pil_image(image)
+        except cozmo.exceptions.SDKShutdown:
+            # SDK is shutting down - Flask will block and spam errors here - force it to exit
+            shutdown_func = request.environ.get('werkzeug.server.shutdown')
+            if shutdown_func is not None:
+                cozmo.logger.info("Shutting down Flask")
+                shutdown_func()
             else:
-                image = image.raw_image
-
-            return flask_helpers.serve_pil_image(image)
+                sys.exit("SDKShutdown")
     return flask_helpers.serve_pil_image(_default_camera_image)
 
 

examples/if_this_then_that/common/__init__.py

@@ -40,8 +40,11 @@ async def get_in_position(self):
         '''If necessary, Move Cozmo's Head and Lift to make it easy to see Cozmo's face'''
         if (self.lift_height.distance_mm > 45) or (self.head_angle.degrees < 40):
             async with self.perform_off_charger():
-                await self.set_lift_height(0.0).wait_for_completed()
-                await self.set_head_angle(cozmo.robot.MAX_HEAD_ANGLE).wait_for_completed()
+                lift_action = self.set_lift_height(0.0, in_parallel=True)
+                head_action = self.set_head_angle(cozmo.robot.MAX_HEAD_ANGLE,
+                                                  in_parallel=True)
+                await lift_action.wait_for_completed()
+                await head_action.wait_for_completed()
 
     def display_image_file_on_face(self, image_name):
         # load image and convert it for display on cozmo's face

examples/tutorials/01_basics/08_animation.py

@@ -27,18 +27,21 @@ def cozmo_program(robot: cozmo.robot.Robot):
     # http://cozmosdk.anki.com/docs/generated/cozmo.anim.html#cozmo.anim.Triggers
     # for a list of available triggers.
     # A trigger can pick from several appropriate animations for variety.
+    print("Playing Animation Trigger 1:")
     robot.play_anim_trigger(cozmo.anim.Triggers.CubePounceLoseSession).wait_for_completed()
 
     # Play the same trigger, but this time ignore the track that plays on the
     # body (i.e. don't move the wheels). See the play_anim_trigger documentation
     # for other available settings.
+    print("Playing Animation Trigger 2: (Ignoring the body track)")
     robot.play_anim_trigger(cozmo.anim.Triggers.CubePounceLoseSession, ignore_body_track=True).wait_for_completed()
 
     # Play an animation via its Name.
     # Warning: Future versions of the app might change these, so for future-proofing
     # we recommend using play_anim_trigger above instead.
     # See the remote_control_cozmo.py example in apps for an easy way to see
     # the available animations.
+    print("Playing Animation 3:")
     robot.play_anim(name="id_poked_giggle").wait_for_completed()
 
 

examples/tutorials/02_cozmo_face/01_cozmo_face_image.py

@@ -32,8 +32,11 @@ def get_in_position(robot: cozmo.robot.Robot):
     '''If necessary, Move Cozmo's Head and Lift to make it easy to see Cozmo's face'''
     if (robot.lift_height.distance_mm > 45) or (robot.head_angle.degrees < 40):
         with robot.perform_off_charger():
-            robot.set_lift_height(0.0).wait_for_completed()
-            robot.set_head_angle(cozmo.robot.MAX_HEAD_ANGLE).wait_for_completed()
+            lift_action = robot.set_lift_height(0.0, in_parallel=True)
+            head_action = robot.set_head_angle(cozmo.robot.MAX_HEAD_ANGLE,
+                                               in_parallel=True)
+            lift_action.wait_for_completed()
+            head_action.wait_for_completed()
 
 
 def cozmo_program(robot: cozmo.robot.Robot):

examples/tutorials/02_cozmo_face/02_cozmo_face_mirror.py

@@ -37,8 +37,11 @@ def get_in_position(robot: cozmo.robot.Robot):
     '''If necessary, Move Cozmo's Head and Lift to make it easy to see Cozmo's face.'''
     if (robot.lift_height.distance_mm > 45) or (robot.head_angle.degrees < 40):
         with robot.perform_off_charger():
-            robot.set_lift_height(0.0).wait_for_completed()
-            robot.set_head_angle(cozmo.robot.MAX_HEAD_ANGLE).wait_for_completed()
+            lift_action = robot.set_lift_height(0.0, in_parallel=True)
+            head_action = robot.set_head_angle(cozmo.robot.MAX_HEAD_ANGLE,
+                                               in_parallel=True)
+            lift_action.wait_for_completed()
+            head_action.wait_for_completed()
 
 
 def calc_pixel_threshold(image: Image):

examples/tutorials/02_cozmo_face/03_alarm_clock.py

@@ -222,8 +222,11 @@ def get_in_position(robot: cozmo.robot.Robot):
     '''If necessary, Move Cozmo's Head and Lift to make it easy to see Cozmo's face'''
     if (robot.lift_height.distance_mm > 45) or (robot.head_angle.degrees < 40):
         with robot.perform_off_charger():
-            robot.set_lift_height(0.0).wait_for_completed()
-            robot.set_head_angle(cozmo.robot.MAX_HEAD_ANGLE).wait_for_completed()
+            lift_action = robot.set_lift_height(0.0, in_parallel=True)
+            head_action = robot.set_head_angle(cozmo.robot.MAX_HEAD_ANGLE,
+                                               in_parallel=True)
+            lift_action.wait_for_completed()
+            head_action.wait_for_completed()
 
 
 def alarm_clock(robot: cozmo.robot.Robot):

examples/tutorials/04_cubes_and_objects/02_create_wall.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright (c) 2016 Anki, Inc.
+# Copyright (c) 2016-2017 Anki, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,9 +16,14 @@
 
 '''Use custom objects to create a wall in front of Cozmo.
 
-This script is meant to show off custom objects.
+This example demonstrates how you can create custom objects in the world, and
+automatically have Cozmo path around them as if they are real obstacles.
+
 It creates a wall in front of cozmo and tells him to drive around it.
 He will plan a path to drive 200mm in front of himself after these objects are created.
+
+The `use_3d_viewer=True` argument causes the 3D visualizer to open in a new
+window - this shows where Cozmo believes this imaginary object is.
 '''
 
 import cozmo
@@ -34,4 +39,4 @@ def cozmo_program(robot: cozmo.robot.Robot):
     robot.go_to_pose(Pose(200, 0, 0, angle_z=degrees(0)), relative_to_robot=True).wait_for_completed()
 
 
-cozmo.run_program(cozmo_program)
+cozmo.run_program(cozmo_program, use_3d_viewer=True)

examples/tutorials/04_cubes_and_objects/04_stack_or_roll.py

@@ -32,7 +32,7 @@ def cozmo_program(robot: cozmo.robot.Robot):
 
     cubes = robot.world.wait_until_observe_num_objects(num=2, object_type=cozmo.objects.LightCube, timeout=10)
 
-    print(cubes)
+    print("Found %s cubes" % len(cubes))
 
     lookaround.stop()
 

examples/tutorials/04_cubes_and_objects/06_pickup_furthest.py

@@ -49,4 +49,4 @@ def cozmo_program(robot: cozmo.robot.Robot):
         robot.pickup_object(targ, num_retries=3).wait_for_completed()
 
 
-cozmo.run_program(cozmo_program)
+cozmo.run_program(cozmo_program, use_viewer=True)

examples/tutorials/04_cubes_and_objects/09_custom_objects.py

@@ -98,4 +98,4 @@ def custom_objects(robot: cozmo.robot.Robot):
         time.sleep(0.1)
 
 
-cozmo.run_program(custom_objects, use_viewer=True, force_viewer_on_top=True)
+cozmo.run_program(custom_objects, use_3d_viewer=True, use_viewer=True)

examples/tutorials/04_cubes_and_objects/11_dock_with_cube.py

@@ -23,13 +23,15 @@
 import cozmo
 
 async def dock_with_cube(robot: cozmo.robot.Robot):
-    print("Cozmo is waiting until he sees a cube")
-
+    print("Cozmo is waiting until he sees a cube.")
     cube = await robot.world.wait_for_observed_light_cube()
 
+    print("Cozmo found a cube, and will now attempt to dock with it:")
     # Cozmo will approach the cube he has seen
     # using a 180 approach angle will cause him to drive past the cube and approach from the opposite side
     # num_retries allows us to specify how many times Cozmo will retry the action in the event of it failing
-    await robot.dock_with_cube(cube, approach_angle=cozmo.util.degrees(180), num_retries=2).wait_for_completed()
+    action = robot.dock_with_cube(cube, approach_angle=cozmo.util.degrees(180), num_retries=2)
+    await action.wait_for_completed()
+    print("result:", action.result)
 
 cozmo.run_program(dock_with_cube)