mirror of
https://github.com/bspeice/libcvautomation
synced 2024-12-05 22:38:09 -05:00
Document the "waitfor" command better
Change locations of some other documentation, move information about the wrapper environment variables to the appendix
This commit is contained in:
Bradlee Speice
parent
9685d442d9
commit
aff47435a9
@ -62,7 +62,7 @@ typedef struct {
|
||||
/* Doxygen information */
|
||||
/** \file libcvautomation.h
|
||||
* \brief The top-level include for all projects involving libcvautomation
|
||||
* \details This source file includes all other files needed for libcvautomation projects, and also defines the cvautomationList and cvaPoint structs to be used among libcvautomation functions. Please note that while the opencv2 version is being documented, there is no actual difference in usage for opencv version 1.
|
||||
* \details This source file includes all other files needed for libcvautomation projects, and also defines the cvautomationList and cvaPoint structs to be used among libcvautomation functions.
|
||||
* \author Bradlee Speice
|
||||
* \date 7/18/2012
|
||||
*/
|
||||
@ -78,7 +78,7 @@ typedef struct {
|
||||
* Basically what happens is that for whenever you need to do image recognition, OpenCV is used to find the images, and XTest is used to generate any events needed. Libcvautomation is mostly a wrapper to integrate both of these products, but also adds some functions like matchSubImage_X11() that allow you to match an image against the X11 root window in place. This means no more <tt>'xwd | convert "<out_name>"'</tt>.
|
||||
* \section main_using Using Libcvautomation And Writing Application Tests
|
||||
* So how does one go about using libcvautomation? <br>
|
||||
* I'm so glad you asked! I've provided a few reference programs - \c cva-match and \c cva-input - that can be used to demonstrate most of libcvautomation's capabilities. I've even provided a BASH wrapper to make it incredibly easy to use BASH with libcvautomation as well (requires that cva-match and cva-input are installed). Python bindings are on their way too. <br>
|
||||
* I'm so glad you asked! I've provided a few reference programs - \c cva-match and \c cva-input - that can be used to demonstrate most of libcvautomation's capabilities. I've even provided a BASH wrapper to make it incredibly easy to use BASH with libcvautomation as well (requires that \c cva-match and \c cva-input are installed). Python bindings are on their way too. <br>
|
||||
* Finally, if you want to know how to write your own application tests, please see \ref writing_app_tests for more information on that. I've provided code to give you a basic idea of how they work.
|
||||
* \section questions Questions? Comments? Concerns?
|
||||
* Please send any feedback to <<a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a>>. Pull requests can be submitted to <a href="https://github.com/DjBushido/libcvautomation">my github repository</a>.*/
|
||||
@ -214,7 +214,7 @@ typedef struct {
|
||||
* #Changing any wrapper parameters should go here
|
||||
* \endcode
|
||||
* <li>The purpose of these lines is just the standard BASH header. Additionally, we import a wrapper created for libcvautomation to make our job easier. Please note that this is the default directory for the wrapper, your installation may be different. Use the command <tt>locate libcvautomation_funcs</tt> to find it on your computer. The wrapper itself is a handful of macros used to make our job easy.
|
||||
* <li>Changing any wrapper parameters should go after sourcing the wrapper functions. See below on \ref testing_test_wrapper for more information.
|
||||
* <li>Changing any wrapper parameters should go after sourcing the wrapper functions. See the \ref wrapper_functions for more information.
|
||||
* <br><br>
|
||||
* \code
|
||||
* start_libreoffice_writer ()
|
||||
@ -230,9 +230,9 @@ typedef struct {
|
||||
* <li>This is the actual body of work done by libcvautomation
|
||||
* <li>\c click_i is a function to click the mouse at an image - in this case, the gnome or kde menu.
|
||||
* <ul>
|
||||
* <li>Because of how the cva-input program is designed, you can give it multiple images, and it will only select the one currently available. See \ref testing_test_wrapper for more information on how to use this (TOLERANCE specifically)
|
||||
* <li>Because of how the cva-input program is designed, you can give it multiple images, and it will only select the one currently available. See the \ref wrapper_functions for more information on how to use this (\c TOLERANCE specifically)
|
||||
* <li>By using the function \c click_i, we make things a bit more readable - the full command line is <tt>cva-input -s 'icmouseclick <filename>'</tt>
|
||||
* <li>See \ref wrapper_functions for a list of all functions available in the wrapper.
|
||||
* <li>See the \ref wrapper_functions for a list of all functions available in the wrapper.
|
||||
* </ul>
|
||||
* <li>\c hover_i is a function to move the mouse to an image - in this case, move it over the LibreOffice menu item.
|
||||
* <li>Then we jiggle the mouse to make sure that the item activates, click, and wait for the program to start up.
|
||||
@ -259,39 +259,8 @@ typedef struct {
|
||||
* \subsection testing_test_wrapper Testing the Testing Wrapper
|
||||
* <ul>
|
||||
* <li>First things first, run through the testing wrapper to make sure that everything is O.K.
|
||||
* <li>If you need to, some things you can do to tune the application test are as follows:
|
||||
* <ul>
|
||||
* <li>Set the \c SEARCH_METHOD
|
||||
* <ul>
|
||||
* <li>This value adjusts how libcvautomation searches for sub-images. See \ref libcvautomation_search_methods for more information on accepted values, and how each works.
|
||||
* </ul>
|
||||
* <li>Set the \c TOLERANCE
|
||||
* <ul>
|
||||
* <li>This value adjusts how strict libcvautomation is when trying to find a sub-image. See \ref libcvautomation_search_methods for more information on how to control how libcvautomation searches for images.
|
||||
* </ul>
|
||||
* <li>Set \c USE_SANE_TOLERANCE
|
||||
* <ul>
|
||||
* <li>This value implements a more sane way of setting the tolerance value - Where normally the tolerance ranges from \c INT_MIN to \c INT_MAX, the sane tolerance accepts values of 1 - 100 (\f$ 1 \approx 0 \f$, and \f$ 100 \approx INT\_MAX \f$)
|
||||
* <li>To enable sane tolerance, set: \code USE_SANE_TOLERANCE="<any_value>" \endcode
|
||||
* <li>To disable sane tolerance (the default) set: \code USE_SANE_TOLERANCE="" \endcode
|
||||
* <li>Set \c USE_CENTER
|
||||
* <ul>
|
||||
* <li>By default, the wrapper will use the center of an image as opposed to the upper-left corner to click on. To disable this behavior, set: \code USE_CENTER="" \endcode
|
||||
* <li>To set the behavior back to using center-based matching, set: \code USE_CENTER="<any_value>" \endcode
|
||||
* </ul>
|
||||
* <li>Set the \c OUTFILE and \c ERRFILE
|
||||
* <ul>
|
||||
* <li>The application wrapper logs a whole lot of information about what it does to make debugging easy. However, to make sure that you're not overwhelmed by the output, the wrapper also directs the output to <tt>/dev/null</tt> by default.
|
||||
* <li>To redirect the output of \c OUTFILE and \c ERRFILE, set them to any file you want. For example, the following code will create a temporary file for OUTFILE and ERRFILE, and notify you of what they are:
|
||||
* \code
|
||||
* OUTFILE=`mktemp`
|
||||
* ERRFILE=`mktemp`
|
||||
* echo "OUTFILE location: $OUTFILE"
|
||||
* echo "ERRFILE location: $ERRFILE"
|
||||
* \endcode
|
||||
* </ul>
|
||||
* </ul>
|
||||
* <li>A full list of commands provided by the wrapper is available at \ref wrapper_functions
|
||||
* <li>If you need to, there are a few environment variables you can set to change how the wrapper works. See \ref appendix_variables for more information on how these work.
|
||||
* <li>A full list of commands provided by the wrapper is available at \ref appendix_functions
|
||||
* </ul>
|
||||
*
|
||||
* \note These options are controlled using the testing script as demonstrated above. Any modifications to the following values should be done at the line: \code #Changing any wrapper parameters should go here \endcode
|
||||
@ -305,8 +274,40 @@ typedef struct {
|
||||
* <li>If you have questions, comments, concerns, suggestions, or feedback in general, feel free to let me know at <a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a>.
|
||||
* </ul>
|
||||
*/
|
||||
/** \page wrapper_functions Appendix of Wrapper Functions
|
||||
* \section appendix_click Click the mouse
|
||||
/** \page wrapper_functions Appendix of Wrapper Functions and Environment Variables
|
||||
* \section appendix_variables Environment Variables
|
||||
* \subsection appendix_search Search Method
|
||||
* \code SEARCH_METHOD \endcode
|
||||
* This controls how each of the functions searches for an image. See \ref libcvautomation_search_methods for more instruction on how to use this option.
|
||||
*
|
||||
* \subsection appendix_tolerance Tolerance
|
||||
* \code TOLERANCE
|
||||
* USE_SANE_TOLERANCE \endcode
|
||||
* These control how tolerant each function is when searching for an image. Acceptable values are anywhere between \c INT_MIN to \c INT_MAX. See \ref libcvautomation_search_methods for more information on how the tolerance values work.
|
||||
* Additionally, the cva-input and cva-match programs (which this wrapper depends on) implement a "sane-tolerance" option. This allows you to set a tolerance between 1 - 100, where: \f$ 1 \approx 0 \f$, and \f$ 100 \approx INT\_MAX \f$
|
||||
* By default, functions will not use sane tolerance. To make the functions search using sane tolerance, set \code USE_SANE_TOLERANCE="yes" \endcode
|
||||
*
|
||||
* \subsection appendix_center Center
|
||||
* \code USE_CENTER \endcode
|
||||
* This controls whether each function will return a value based on the center of the sub-image, rather than the top-left corner.
|
||||
* By default, functions will use center-based matching. To make the functions use the top-left corner, set \code USE_CENTER="" \endcode
|
||||
*
|
||||
* \subsection appendix_wait Wait
|
||||
* \code USE_WAIT
|
||||
* TIMEOUT \endcode
|
||||
* These control how the "waitfor" function is used. By default, all image-matching functions will wait for an image to appear, and then click on it. This way, it won't click randomly if it can or can't find an image, and provides very easy error recognition. The functions will wait for a period of \c TIMEOUT seconds before complaining.
|
||||
* To disable waiting before performing an action, set \code USE_WAIT="" \endcode
|
||||
*
|
||||
* \subsection appendix_output Output and Debugging
|
||||
* \code OUTFILE
|
||||
* ERRFILE \endcode
|
||||
* These files control the reporting of libcvautomation_funcs. The wrapper generates a decent amount of output to help in debugging application tests, and by default these get redirected to /dev/null. To instead redirect them to a file, you can do something like this:
|
||||
* \code OUTFILE=`mktemp`; echo "Logfile: " $OUTFILE
|
||||
* ERRFILE=`mktemp`; echo "Error file: " $ERR_FILE \endcode
|
||||
* This will redirect the output and error output to a file you own, and inform you of what that file is.
|
||||
*
|
||||
* \section appendix_functions Functions
|
||||
* \subsection appendix_click Click the mouse
|
||||
* \code click \endcode
|
||||
* Click the mouse where it is currently located
|
||||
* <br><br>
|
||||
@ -324,10 +325,10 @@ typedef struct {
|
||||
*
|
||||
* \code click_i <filename> \endcode
|
||||
* Click the mouse on a screenshot from \c filename
|
||||
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref testing_test_wrapper for more information on these.
|
||||
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref appendix_variables for more information on these.
|
||||
* <br><br>
|
||||
*
|
||||
* \section appendix_move Move the mouse
|
||||
* \subsection appendix_move Move the mouse
|
||||
* \code hover_xy <x-coordinate> <y-increment> \endcode
|
||||
* Move the mouse to a location on screen using absolute positioning
|
||||
* <br><br>
|
||||
@ -339,7 +340,7 @@ typedef struct {
|
||||
*
|
||||
* \code hover_i <filename> \endcode
|
||||
* Move the mouse to a location on screen based on screenshot
|
||||
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref testing_test_wrapper for more information on these.
|
||||
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref appendix_variables for more information on these.
|
||||
* <br><br>
|
||||
*
|
||||
* \code mouse_scrollu \endcode
|
||||
@ -348,13 +349,17 @@ typedef struct {
|
||||
* \code mouse_scrolld \endcode
|
||||
* Scroll the mouse wheel down one
|
||||
*
|
||||
* \section appendix_find Find an Image
|
||||
* \subsection appendix_find Find an Image
|
||||
* \code image_location <filename> \endcode
|
||||
* Get the location of an image on screen
|
||||
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref testing_test_wrapper for more information on these.
|
||||
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref appendix_variables for more information on these.
|
||||
* <br><br>
|
||||
*
|
||||
* \section appendix_keyboard Click the keyboard
|
||||
* \code waitfor <filename> \endcode
|
||||
* Wait for an image to display on screen
|
||||
* \note This is affected by the \c TOLERANCE, \c SEARCH_METHOD, and \c TIMEOUT variables. See \ref appendix_variables for more information on these.
|
||||
*
|
||||
* \subsection appendix_keyboard Click the keyboard
|
||||
* \code key_str "<string>" \endcode
|
||||
* Enter a string of characters on the keyboard rather than a single character at a time.
|
||||
* \warning This function <b>does not</b> accept key strings like "Space" as \c key_down, \c key_up, and \c key_click do. If you pass in "Space", that is exactly what will be typed.
|
||||
@ -375,7 +380,7 @@ typedef struct {
|
||||
* \note This function accepts special keys like "Space" - see \ref xtest_key_strings for a full list of characters allowed.
|
||||
* <br><br>
|
||||
*
|
||||
* \section appendix_utilities Useful extras
|
||||
* \subsection appendix_utilities Useful extras
|
||||
* \code run_process "<process-name>" \endcode
|
||||
* Start a process on the system, background it, and return the PID of the created process.
|
||||
* <br><br>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user