Skip to content

Commit 1750cd0

Browse files
johnwasonjohnwason
authored
Update readme (#35)
1 parent 93cdc84 commit 1750cd0

File tree

1 file changed

+193
-118
lines changed

1 file changed

+193
-118
lines changed

‎README.md

Lines changed: 193 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,165 +1,240 @@
11
# Tesseract Python
22

3-
[![codecov](https://codecov.io/gh/ros-industrial-consortium/tesseract_python/branch/master/graph/badge.svg)](https://codecov.io/gh/ros-industrial-consortium/tesseract_python)
3+
[![Python](https://img.shields.io/badge/python-3.7+-blue.svg)](https://github.com/tesseract-robotics/tesseract_python)
44

5-
[![Python](https://img.shields.io/badge/python-2.7+|3.6+-blue.svg)](https://github.com/ros-industrial-consortium/tesseract_python)
5+
![PyPI](https://img.shields.io/pypi/v/tesseract-robotics)
66

77
Platform | CI Status
88
---------------------|:---------
9-
Linux (Focal) | [![Build Status](https://github.com/ros-industrial-consortium/tesseract_python/workflows/Focal-Build/badge.svg)](https://github.com/ros-industrial-consortium/tesseract_python/actions)
10-
Linux (Bionic) | [![Build Status](https://github.com/ros-industrial-consortium/tesseract_python/workflows/Bionic-Build/badge.svg)](https://github.com/ros-industrial-consortium/tesseract_python/actions)
11-
Windows | [![Build Status](https://github.com/ros-industrial-consortium/tesseract_python/workflows/Windows-Noetic-Build/badge.svg)](https://github.com/ros-industrial-consortium/tesseract_python/actions)
9+
Linux (Focal) | [![Build Status](https://github.com/tesseract-robotics/tesseract_python/workflows/Focal-Build/badge.svg)](https://github.com/tesseract-robotics/tesseract_python/actions)
10+
Windows | [![Build Status](https://github.com/tesseract-robotics/tesseract_python/workflows/Windows-Noetic-Build/badge.svg)](https://github.com/tesseract-robotics/tesseract_python/actions)
11+
Wheels | [![Build Status](https://github.com/tesseract-robotics/tesseract_python/actions/workflows/wheels.yml/badge.svg)](https://github.com/tesseract-robotics/tesseract_python/actions)
1212

13-
[![Github Issues](https://img.shields.io/github/issues/ros-industrial-consortium/tesseract.svg)](http://github.com/ros-industrial-consortium/tesseract/issues)
13+
[![Github Issues](https://img.shields.io/github/issues/tesseract-robotics/tesseract_python.svg)](http://github.com/tesseract-robotics/tesseract_python/issues)
1414

1515
[![license - apache 2.0](https://img.shields.io/:license-Apache%202.0-yellowgreen.svg)](https://opensource.org/licenses/Apache-2.0)
1616
[![license - bsd 2 clause](https://img.shields.io/:license-BSD%202--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)
1717

1818
[![support level: consortium](https://img.shields.io/badge/support%20level-consortium-brightgreen.png)](http://rosindustrial.org/news/2016/10/7/better-supporting-a-growing-ros-industrial-software-platform)
1919

20-
Python wrapper for Tesseract package
20+
`tesseract_python` contains Python wrappers for the Tesseract robot motion planner, generated using SWIG. These wrappers
21+
contain most of the Tesseract functionality, including scene loading and management (URDF,SRDF, meshes), collision
22+
checking (Bullet, FCL), kinematics (KDL, OPW, UR), planning (OMPL, Descartes, TrajOpt), and visualization
23+
(tesseract_viewer_python)
2124

22-
## Tesseract Setup Wizard and Visualization Tools
25+
Standalone packages are provided on PyPi (pip install) for Windows and Linux, containing all the native dependencies
26+
for Python 3.7+.
2327

24-
[![](https://github.com/snapcore/snap-store-badges/blob/master/EN/%5BEN%5D-snap-store-black-uneditable%401x.png)](https://snapcraft.io/tesseract-ignition)
28+
**Note that these are low level wrappers.** The lifecycle of objects follow the underlying C++ objects, meaning
29+
that the target of C++ references may be destroyed before the reference, leading to a memory error. These wrappers
30+
do not attempt to change the memory lifecycle of the underlying C++ objects.
2531

26-
## Tesseract Python Supported Packages
27-
28-
* **tesseract_collision** – This package contains privides a common interface for collision checking prividing several implementation of a Bullet collision library and FCL collision library. It includes both continuous and discrete collision checking for convex-convex, convex-concave and concave-concave shapes.
29-
* **tesseract_common** – This package contains common functionality needed by the majority of the packages.
30-
* **tesseract_environment** – This package contains the Tesseract Environment which provides functionality to add,remove,move and modify links and joint. It also manages adding object to the contact managers and provides the ability.
31-
* **tesseract_geometry** – This package contains geometry types used by Tesseract including primitive shapes, mesh, convex hull mesh, octomap and signed distance field.
32-
* **tesseract_kinematics** – This package contains a common interface for Forward and Inverse kinematics for Chain, Tree's and Graphs including implementation using KDL and OPW Kinematics.
33-
* **tesseract_scene_graph** – This package contains the scene graph which is the data structure used to manage the connectivity of objects in the environment. It inherits from boost graph and provides addition functionality for adding,removing and modifying Links and Joints along with search implementation.
34-
* **tesseract_support** – This package contains support data used for unit tests and examples throughout Tesseract.
35-
* **tesseract_urdf** - This package contains a custom urdf parser supporting addition shapes and features currently not supported by urdfdom.
36-
* **tesseract_visualization** – This package contains visualization utilities and libraries.
37-
* **tesseract_command_language** - This is a generic programing language used as input for motion and process planning. It is very similar to how you currently program a robot on an industrial teach pendant.
38-
* **tesseract_motion_planners** – This package contains a common interface for Planners and includes implementation for OMPL, TrajOpt, TrajOpt IFOPT and Descartes.
39-
* **tesseract_process_managers** – This package contains a common interface for Process Planning and includes implementation for a wide variaty of process found industrial automation like painting, griding, welding, pick and place and more.
40-
* **tesseract_time_parameterization** – This package contains a time parameterization algorithms and includes iteritive spline.
32+
## Installation
4133

42-
## Related Repositories
34+
Standalone packages are provided on PyPi (pip install) for Windows and Linux, containing Tesseract, Tesseract
35+
Planning, andall the native dependencies
36+
for Python 3.7+. These packages have been tested on Windows 10, Ubuntu 20.04, and Ubuntu 22.04, but should work
37+
on any relatively recent x64 Windows or Linux operating system. Packages are available for Python 3.7 - 3.10.
4338

44-
* [Tesseract](https://github.com/ros-industrial-consortium/tesseract)
45-
* [Tesseract ROS](https://github.com/ros-industrial-consortium/tesseract_ros)
46-
47-
## Documentation
48-
49-
* [Wiki](https://ros-industrial-tesseract-python.rtfd.io)
50-
* [Doxygen](https://ros-industrial-consortium.github.io/tesseract_python/)
51-
* [Benchmark](https://ros-industrial-consortium.github.io/tesseract_python/dev/bench)
52-
53-
## Evolution
54-
55-
[![Tesseract Evolution Video](gh_pages/_static/tesseract_evolution.png)](https://www.youtube.com/watch?v=rxlzlsSBxAY)
39+
To install on Windows:
40+
```
41+
python -m pip install tesseract-robotics tesseract-robotics-viewer
42+
```
43+
To install on Ubuntu 20.04 and Ubuntu 22.04:
5644

57-
How to create:
45+
```
46+
sudo apt install python3-pip python3-numpy
47+
# The supplied version of pip on Ubuntu 20.04 is too old for manylinux_2_31, upgrade pip
48+
python3 -m pip install -U pip
49+
python3 -m pip install --user tesseract_robotics tesseract_robotics_viewer
50+
```
5851

59-
* Create Video: `gource -1280x720 -seconds-per-day 0.2 --auto-skip-seconds 0.2 --disable-bloom -background d0d3d4 --hide filenames,mouse,progress -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i - -vcodec libx264 -preset ultrafast -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 gource.mp4`
60-
* Create Gif: `ffmpeg -i gource.mp4 -r 10 -vf "scale=800:-1,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" tesseract_evolution.gif`
52+
## Example
6153

62-
## TODO's
54+
ABB Tesseract viewer plan and viewer example:
6355

64-
Warning: These packages are under heavy development and are subject to change.
56+
Install `tesseract_robotics` and `tesseract_robotics_viewer` as shown in Installation section.
6557

66-
See [issue #66](https://github.com/ros-industrial-consortium/tesseract/issues/66)
58+
Clone `tesseract` and `tesseract_python` repositories to retrieve example assets. This is not necessary
59+
if the example assets are not used.
6760

68-
## Build Instructions
61+
```
62+
git clone --depth=1 https://github.com/tesseract-robotics/tesseract.git
63+
git clone --depth=1 https://github.com/tesseract-robotics/tesseract_python.git
64+
```
6965

70-
1) Clone repository into your workspace
71-
2) Clone the repositories in the dependencies.rosinstall file using wstool or some other method (e.g. manually git cloning them)
72-
3) Build the workspace using catkin tools, colcon, or a similar tool
66+
Set the `TESSERACT_SUPPORT_DIR` so the example can find the URDF resources:
7367

74-
NOTE: To speed up clean build you may want to add tesseract_ext to an extended workspace.
68+
Linux:
7569

76-
NOTE: Install TaskFlow from [ROS-Industrial PPA](https://launchpad.net/~ros-industrial/+archive/ubuntu/ppa).
70+
```
71+
export TESSERACT_SUPPORT_DIR=`pwd`/tesseract/tesseract_support
72+
```
7773

78-
### Building with Clang-Tidy Enabled
74+
Windows:
7975

80-
Must pass the -DTESSERACT_ENABLE_CLANG_TIDY=ON to cmake when building. This is automatically enabled if cmake argument -DTESSERACT_ENABLE_TESTING_ALL=ON is passed.
76+
```
77+
set TESSERACT_SUPPORT_DIR=%CD%/tesseract/tesseract_support
78+
```
8179

82-
### Building Tests
80+
Now run the example!
8381

84-
Must pass the -DTESSERACT_ENABLE_TESTING=ON to cmake when wanting to build tests. This is automatically enabled if cmake argument -DTESSERACT_ENABLE_TESTING_ALL=ON is passed.
82+
Windows:
8583

86-
NOTE: If you are building using catkin tools, use `catkin build --force-cmake -DTESSERACT_ENABLE_TESTING=ON`.
84+
```
85+
cd tesseract_python\tesseract_viewer_python\examples
86+
python abb_irb2400_viewer.py
87+
```
8788

88-
#### Running Tests
89+
Linux:
8990

90-
Tesseract packages use ctest because it is ROS agnostic, so to run the test call `catkin test --no-deps tesseract_python`
91+
```
92+
cd tesseract_python/tesseract_viewer_python/examples
93+
python3 abb_irb2400_viewer.py
94+
```
9195

92-
### Building Code Coverage
96+
And point a modern browser to `http://localhost:8000` to see the animation!
97+
98+
Example source:
99+
100+
```python
101+
from tesseract_robotics.tesseract_common import FilesystemPath, Isometry3d, Translation3d, Quaterniond, \
102+
ManipulatorInfo
103+
from tesseract_robotics.tesseract_environment import Environment
104+
from tesseract_robotics.tesseract_common import ResourceLocator, SimpleLocatedResource
105+
from tesseract_robotics.tesseract_command_language import CartesianWaypoint, Waypoint, \
106+
MoveInstructionType_FREESPACE, MoveInstructionType_START, MoveInstruction, Instruction, \
107+
CompositeInstruction, flatten
108+
from tesseract_robotics.tesseract_process_managers import ProcessPlanningServer, ProcessPlanningRequest, \
109+
FREESPACE_PLANNER_NAME
110+
import os
111+
import re
112+
import traceback
113+
from tesseract_robotics_viewer import TesseractViewer
114+
import numpy as np
115+
import time
116+
import sys
117+
118+
TESSERACT_SUPPORT_DIR = os.environ["TESSERACT_SUPPORT_DIR"]
119+
120+
class TesseractSupportResourceLocator(ResourceLocator):
121+
def __init__(self):
122+
super().__init__()
123+
124+
def locateResource(self, url):
125+
try:
126+
try:
127+
if os.path.exists(url):
128+
return SimpleLocatedResource(url, url, self)
129+
except:
130+
pass
131+
url_match = re.match(r"^package:\/\/tesseract_support\/(.*)$",url)
132+
if (url_match is None):
133+
print("url_match failed")
134+
return None
135+
if not "TESSERACT_SUPPORT_DIR" in os.environ:
136+
return None
137+
tesseract_support = os.environ["TESSERACT_SUPPORT_DIR"]
138+
filename = os.path.join(tesseract_support, os.path.normpath(url_match.group(1)))
139+
ret = SimpleLocatedResource(url, filename, self)
140+
return ret
141+
except:
142+
traceback.print_exc()
143+
144+
abb_irb2400_urdf_fname = FilesystemPath(os.path.join(TESSERACT_SUPPORT_DIR,"urdf","abb_irb2400.urdf"))
145+
abb_irb2400_srdf_fname = FilesystemPath(os.path.join(TESSERACT_SUPPORT_DIR,"urdf","abb_irb2400.srdf"))
146+
147+
t_env = Environment()
148+
149+
# locator_fn must be kept alive by maintaining a reference
150+
locator = TesseractSupportResourceLocator()
151+
t_env.init(abb_irb2400_urdf_fname, abb_irb2400_srdf_fname, locator)
152+
153+
manip_info = ManipulatorInfo()
154+
manip_info.tcp_frame = "tool0"
155+
manip_info.manipulator = "manipulator"
156+
manip_info.working_frame = "base_link"
157+
158+
viewer = TesseractViewer()
159+
160+
viewer.update_environment(t_env, [0,0,0])
161+
162+
joint_names = ["joint_%d" % (i+1) for i in range(6)]
163+
viewer.update_joint_positions(joint_names, np.array([1,-.2,.01,.3,-.5,1]))
164+
165+
viewer.start_serve_background()
166+
167+
t_env.setState(joint_names, np.ones(6)*0.1)
168+
169+
wp1 = CartesianWaypoint(Isometry3d.Identity() * Translation3d(0.8,-0.3,1.455) * Quaterniond(0.70710678,0,0.70710678,0))
170+
wp2 = CartesianWaypoint(Isometry3d.Identity() * Translation3d(0.8,0.3,1.455) * Quaterniond(0.70710678,0,0.70710678,0))
171+
wp3 = CartesianWaypoint(Isometry3d.Identity() * Translation3d(0.8,0.3,1) * Quaterniond(0.70710678,0,0.70710678,0))
172+
173+
start_instruction = MoveInstruction(Waypoint(wp1), MoveInstructionType_START, "DEFAULT")
174+
plan_f1 = MoveInstruction(Waypoint(wp2), MoveInstructionType_FREESPACE, "DEFAULT")
175+
176+
program = CompositeInstruction("DEFAULT")
177+
program.setStartInstruction(Instruction(start_instruction))
178+
program.setManipulatorInfo(manip_info)
179+
program.append(Instruction(plan_f1))
180+
181+
planning_server = ProcessPlanningServer(t_env, 1)
182+
planning_server.loadDefaultProcessPlanners()
183+
request = ProcessPlanningRequest()
184+
request.name = FREESPACE_PLANNER_NAME
185+
request.instructions = Instruction(program)
186+
187+
response = planning_server.run(request)
188+
planning_server.waitForAll()
189+
190+
assert response.interface.isSuccessful()
191+
192+
results = flatten(response.problem.getResults().as_CompositeInstruction())
193+
194+
viewer.update_trajectory(joint_names, results)
195+
196+
if sys.version_info[0] < 3:
197+
input("press enter")
198+
else:
199+
input("press enter")
93200

94-
Must pass the -DTESSERACT_ENABLE_CODE_COVERAGE=ON to cmake when wanting to build code coverage. The code coverage report is located in each individuals build directory inside a ccov/all-merged folder. Open the index.html file to see the packages code coverage report.
201+
```
95202

96-
NOTE: Must be a clean build when generating a code coverage report. Also must build in debug.
203+
## Tesseract Python Supported Packages
97204

98-
#### Exclude Code From Code Coverage
205+
* **tesseract_collision** – This package contains privides a common interface for collision checking prividing several implementation of a Bullet collision library and FCL collision library. It includes both continuous and discrete collision checking for convex-convex, convex-concave and concave-concave shapes.
206+
* **tesseract_common** – This package contains common functionality needed by the majority of the packages.
207+
* **tesseract_environment** – This package contains the Tesseract Environment which provides functionality to add,remove,move and modify links and joint. It also manages adding object to the contact managers and provides the ability.
208+
* **tesseract_geometry** – This package contains geometry types used by Tesseract including primitive shapes, mesh, convex hull mesh, octomap and signed distance field.
209+
* **tesseract_kinematics** – This package contains a common interface for Forward and Inverse kinematics for Chain, Tree's and Graphs including implementation using KDL and OPW Kinematics.
210+
* **tesseract_scene_graph** – This package contains the scene graph which is the data structure used to manage the connectivity of objects in the environment. It inherits from boost graph and provides addition functionality for adding,removing and modifying Links and Joints along with search implementation.
211+
* **tesseract_support** – This package contains support data used for unit tests and examples throughout Tesseract.
212+
* **tesseract_urdf** - This package contains a custom urdf parser supporting addition shapes and features currently not supported by urdfdom.
213+
* **tesseract_visualization** – This package contains visualization utilities and libraries.
214+
* **tesseract_command_language** - This is a generic programing language used as input for motion and process planning. It is very similar to how you currently program a robot on an industrial teach pendant.
215+
* **tesseract_motion_planners** – This package contains a common interface for Planners and includes implementation for OMPL, TrajOpt, TrajOpt IFOPT and Descartes.
216+
* **tesseract_process_managers** – This package contains a common interface for Process Planning and includes implementation for a wide variaty of process found industrial automation like painting, griding, welding, pick and place and more.
217+
* **tesseract_time_parameterization** – This package contains a time parameterization algorithms and includes iteritive spline.
99218

100-
- LCOV_EXCL_LINE
101-
- Lines containing this marker will be excluded.
102-
- LCOV_EXCL_START
103-
- Marks the beginning of an excluded section. The current line is part of this section.
104-
- LCOV_EXCL_STOP
105-
- Marks the end of an excluded section. The current line not part of this section.
219+
## Related Repositories
106220

107-
.. NOTE: You can replace **LCOV** above with **GCOV** or **GCOVR**.
221+
* [Tesseract](https://github.com/tesseract-robotics/tesseract)
222+
* [Tesseract Planning](https://github.com/tesseract-robotics/tesseract_planning)
223+
* [Tesseract ROS](https://github.com/tesseract-robotics/tesseract_ros)
108224

109-
## Quality Tools Leverage
225+
## Documentation
110226

111-
Tesseract currently leverages Compiler Warnigs, Clang Tidy and Code Coverage. All warnings produced by Compiler and Clang Tidy are treated as errors during CI builds.
227+
* [Wiki](https://ros-industrial-tesseract-python.rtfd.io)
228+
* [Doxygen](https://tesseract-robotics.github.io/tesseract_python/)
229+
* [Benchmark](https://tesseract-robotics.github.io/tesseract_python/dev/bench)
112230

113-
- Compiler
114-
- Wall
115-
- Wextra
116-
- Wconversion
117-
- Wsign-conversion
118-
- Wno-sign-compare
119-
- Wnon-virtual-dtor
120-
- Clang Tidy
121-
- clang-analyzer-*
122-
- bugprone-*
123-
- cppcoreguidelines-avoid-goto
124-
- cppcoreguidelines-c-copy-assignment-signature
125-
- cppcoreguidelines-interfaces-global-init
126-
- cppcoreguidelines-narrowing-conversions
127-
- cppcoreguidelines-no-malloc
128-
- cppcoreguidelines-slicing
129-
- cppcoreguidelines-special-member-functions
130-
- misc-*,-misc-non-private-member-variables-in-classes
131-
- modernize-*,-modernize-use-trailing-return-type,-modernize-use-nodiscard
132-
- performance-*
133-
- readability-avoid-const-params-in-decls
134-
- readability-container-size-empty
135-
- readability-delete-null-pointer
136-
- readability-deleted-default
137-
- readability-else-after-return
138-
- readability-function-size
139-
- readability-identifier-naming
140-
- readability-inconsistent-declaration-parameter-name
141-
- readability-misleading-indentation
142-
- readability-misplaced-array-index
143-
- readability-non-const-parameter
144-
- readability-redundant-*
145-
- readability-simplify-*
146-
- readability-static-*
147-
- readability-string-compare
148-
- readability-uniqueptr-delete-release
149-
- readability-rary-objects
231+
## TODO's
150232

151-
## Build Branch Sphinx Documentation
233+
Warning: These packages are under heavy development and are subject to change.
152234

153-
```
154-
cd gh_pages
155-
sphinx-build . output
156-
```
157-
Now open gh_pages/output/index.rst and remove *output* directory before commiting changes.
235+
See [issue #66](https://github.com/tesseract-robotics/tesseract/issues/66)
158236

159-
## Debugging Windows Build
237+
## Build Instructions
160238

161-
- Search Directories CI
162-
- dir /s /b c:\opt\ros\noetic\*assimp*
163-
- Location of ROS Windows Builds
164-
- https://ros-win.visualstudio.com/ros-win/_build
165-
- https://ros-win.visualstudio.com/ros-win/_build/results?buildId=8711&view=artifacts&type=publishedArtifacts
239+
Building the tesseract_python package is complicated and not recommended for novice users. See the wheels.yml
240+
workflow for details on how to build the packages and all dependencies.

0 commit comments

Comments
 (0)