From 1285d6008910cbae4150bc3fb62c4788ca509627 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Fri, 9 Feb 2024 09:00:14 -0500 Subject: [PATCH] add docs for image_rotate/publisher (#936) --- image_publisher/doc/changes.rst | 12 ++ image_publisher/doc/components.rst | 22 ++++ image_publisher/doc/conf.py | 194 +++++++++++++++++++++++++++++ image_publisher/doc/index.rst | 25 ++++ image_rotate/doc/changes.rst | 12 ++ image_rotate/doc/components.rst | 63 ++++++++++ image_rotate/doc/conf.py | 194 +++++++++++++++++++++++++++++ image_rotate/doc/index.rst | 36 ++++++ image_view/doc/changes.rst | 4 + 9 files changed, 562 insertions(+) create mode 100644 image_publisher/doc/changes.rst create mode 100644 image_publisher/doc/components.rst create mode 100644 image_publisher/doc/conf.py create mode 100644 image_publisher/doc/index.rst create mode 100644 image_rotate/doc/changes.rst create mode 100644 image_rotate/doc/components.rst create mode 100644 image_rotate/doc/conf.py create mode 100644 image_rotate/doc/index.rst diff --git a/image_publisher/doc/changes.rst b/image_publisher/doc/changes.rst new file mode 100644 index 000000000..264172a21 --- /dev/null +++ b/image_publisher/doc/changes.rst @@ -0,0 +1,12 @@ +Changelog Notes +=============== + +Jazzy Jalisco +------------- +There are several major change between ``Iron`` and ``Jazzy``: + + * All components now properly support ``image_transport`` parameter. + * All components now properly support remapping the ``camera_info`` topic + for an associated ``image`` topic. For instance, if you remap ``image`` + to ``my/image`` then ``my/camera_info`` will be used. Previously you + would have to manually remap the ``camera_info`` topic. diff --git a/image_publisher/doc/components.rst b/image_publisher/doc/components.rst new file mode 100644 index 000000000..afd7fcf5e --- /dev/null +++ b/image_publisher/doc/components.rst @@ -0,0 +1,22 @@ +Nodes and Components +==================== + +image_publisher::ImagePublisher +------------------------------- +Component to publish sensor_msgs/Image, requires filename argument. +Also avialable as a ROS 2 node named ``image_publisher``. + +Published Topics +^^^^^^^^^^^^^^^^ + * **image_raw** (sensor_msgs/Image): ROS Image message of your input file. + * **camera_info** (sensor_msgs/CameraInfo): CameraInfo published along with Image. + +Parameters +^^^^^^^^^^ + * **filename** (string, default: ""): Name of image file to be published. + * **flip_horizontal** (bool, default: false): Flip output image horizontally. + * **flip_vertical** (bool, default: false): Flip output image vertically. + * **frame_id** (string, default: "camera") Frame id inserted in published + image and camera_info. + * **publish_rate** (double, default: 10): Rate to publish image (hz). + * **camera_info_uri** (string, default: ""): Path to camera info. diff --git a/image_publisher/doc/conf.py b/image_publisher/doc/conf.py new file mode 100644 index 000000000..8e3c7b78a --- /dev/null +++ b/image_publisher/doc/conf.py @@ -0,0 +1,194 @@ +# Copyright 2024 Open Source Robotics Foundation, 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 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. + +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'image_publisher' +copyright = '2008-2024, Open Source Robotics Foundation, Inc.' # noqa +author = 'Open Source Robotics Foundation, Inc.' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '3.2.1' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.doctest', + 'sphinx.ext.coverage', + 'sphinx_rtd_theme', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'image_publisher_doc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'image_publisher', 'image_publisher Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'image_publisher', 'image_publisher Documentation', + author, 'image_publisher', 'ROS 2 components for image processing.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +autoclass_content = 'both' + +autodoc_default_options = { + 'members': True, # document members + 'undoc-members': True, # also document members without documentation +} diff --git a/image_publisher/doc/index.rst b/image_publisher/doc/index.rst new file mode 100644 index 000000000..10967899a --- /dev/null +++ b/image_publisher/doc/index.rst @@ -0,0 +1,25 @@ +Overview +======== + +``image_publisher`` provides a node/component for publishing images +as a ROS 2 image topic. + +Simplest example is: + +.. code-block: bash + + ros2 run image_publisher image_publisher /opt/ros/rolling/share/rviz/images/splash.png + +.. toctree:: + :maxdepth: 2 + + self + components + changes + image_publisher + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/image_rotate/doc/changes.rst b/image_rotate/doc/changes.rst new file mode 100644 index 000000000..264172a21 --- /dev/null +++ b/image_rotate/doc/changes.rst @@ -0,0 +1,12 @@ +Changelog Notes +=============== + +Jazzy Jalisco +------------- +There are several major change between ``Iron`` and ``Jazzy``: + + * All components now properly support ``image_transport`` parameter. + * All components now properly support remapping the ``camera_info`` topic + for an associated ``image`` topic. For instance, if you remap ``image`` + to ``my/image`` then ``my/camera_info`` will be used. Previously you + would have to manually remap the ``camera_info`` topic. diff --git a/image_rotate/doc/components.rst b/image_rotate/doc/components.rst new file mode 100644 index 000000000..cb6b77273 --- /dev/null +++ b/image_rotate/doc/components.rst @@ -0,0 +1,63 @@ +Nodes and Components +==================== + +image_rotate::ImageRotateNode +----------------------------- +Node to rotate an image for visualization. The node takes a source +vector and a target vector, and projects them onto the camera image. +It then rotates the image by the angle neded to align the projection +of the source vector with the projection of the target vector. +The source and target vectors are specified in arbitrary TF +frames allowing the rotation angle to vary dynamically as frames +move relative to one another. With the default settings, the image +will be rotated so that the top of the image matches the up +direction the base_link. + +Subscribed Topics +^^^^^^^^^^^^^^^^^ + * **image** (sensor_msgs/Image): Image to be rotated. + * **camera_info** (sensor_msgs/CameraInfo): Camera metadata, only + used if ``use_camera_info`` is set to true. + +Published Topics +^^^^^^^^^^^^^^^^ + * **rotated/image** (sensor_msgs/Image): Rotated image. + * **out/camera_info** (sensor_msgs/CameraInfo): Camera metadata, with binning and + ROI fields adjusted to match output raw image. + +Parameters +^^^^^^^^^^ + * **target_frame_id** (str, default: base_link): Frame in which the target + vector is specified. Empty means the input frame. + * **target_x** (double, default: 0.0): X coordinate of the target vector. + Range: -10.0 to 10.0. + * **target_y** (double, default: 0.0): Y coordinate of the target vector. + Range: -10.0 to 10.0. + * **target_z** (double, default: 1.0): Z coordinate of the target vector, + Range: -10.0 to 10.0. + * **source_frame_id** (str, default: ""): Frame in which the source vector + is specified. Empty means the input frame. + * **source_x** (double, default: 0.0): X coordinate of the direction the + target should be aligned with. Range: -10.0 to 10.0. + * **source_y** (double, default: 0.0): Y coordinate of the direction the + target should be aligned with. Range: -10.0 to 10.0. + * **source_z** (double, default: 1.0): Z coordinate of the direction the + target should be aligned with. Range: -10.0 to 10.0. + * **input_frame_id** (str, default: ""): Frame to use for the original camera + image. Empty means that the frame in the image or camera_info should be + used depending on use_camera_info. + * **output_frame_id** (str, default: ""): Frame to publish for the image's + new orientation. Empty means add '_rotated' suffix to the image frame. + * **use_camera_info** (bool, default: True): Indicates that the camera_info + topic should be subscribed to to get the default input_frame_id. + Otherwise the frame from the image message will be used. + * **max_angular_rate** (double, default: 10.0): Limits the rate at which + the image can rotate (rad/s). Zero means no limit. Range: 0.0 to 100.0. + * **output_image_size** (double, default: 2.0): Size of the output image + as a function of the input image size. Can be varied continuously between + the following special settings: + + * 0 ensures no black ever appears + * 1 is small image dimension + * 2 is large image dimension + * 3 is image diagonal diff --git a/image_rotate/doc/conf.py b/image_rotate/doc/conf.py new file mode 100644 index 000000000..d836ccee4 --- /dev/null +++ b/image_rotate/doc/conf.py @@ -0,0 +1,194 @@ +# Copyright 2024 Open Source Robotics Foundation, 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 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. + +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'image_rotate' +copyright = '2008-2024, Open Source Robotics Foundation, Inc.' # noqa +author = 'Open Source Robotics Foundation, Inc.' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '3.2.1' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.doctest', + 'sphinx.ext.coverage', + 'sphinx_rtd_theme', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'image_rotate_doc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'image_rotate', 'image_rotate Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'image_rotate', 'image_rotate Documentation', + author, 'image_rotate', 'ROS 2 components for image processing.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +autoclass_content = 'both' + +autodoc_default_options = { + 'members': True, # document members + 'undoc-members': True, # also document members without documentation +} diff --git a/image_rotate/doc/index.rst b/image_rotate/doc/index.rst new file mode 100644 index 000000000..45a574ea7 --- /dev/null +++ b/image_rotate/doc/index.rst @@ -0,0 +1,36 @@ +Overview +======== + +This package contains a node that rotates an image stream in a way that +minimizes the angle between a vector in some arbitrary frame and a vector +in the camera frame. The frame of the outgoing image is published by the +node. + +This node is intended to allow camera images to be visualized in an +orientation that is more intuitive than the hardware-constrained +orientation of the physical camera. This is particularly helpful, +for example, to show images from the PR2's forearm cameras with a +consistent up direction, despite the fact that the forearms need to +rotate in arbitrary ways during manipulation. + +It is not recommended to use the output from this node for further +computation, as it interpolates the source image, introduces black +borders, and does not output a ``camera_info``. + +|image_rotate| + +.. |image_rotate| image:: images/image_rotate.jpg + +.. toctree:: + :maxdepth: 2 + + self + components + changes + image_rotate + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/image_view/doc/changes.rst b/image_view/doc/changes.rst index 3f14b6aaf..64ecdacae 100644 --- a/image_view/doc/changes.rst +++ b/image_view/doc/changes.rst @@ -6,3 +6,7 @@ Jazzy Jalisco There are several major change between ``Iron`` and ``Jazzy``: * All components now properly support ``image_transport`` parameter. + * ExtractImages: incorrectly named parameter ``transport`` was renamed + to more consistent ``image_transport``. + * StereoView: incorrectly named parameter ``transport`` was renamed + to more consistent ``image_transport``. \ No newline at end of file