# SPDX-License-Identifier: GPL-2.0-or-later r""" Overview ======== This is a utility to generate events from the command line, so reproducible test cases can be written without having to create a custom script each time. The key differentiating feature for this utility as is that it's able to control modal operators. Possible use cases for this script include: - Creating reproducible user interactions for the purpose of benchmarking and profiling. Note that cursor-motion actions report the update time between events which can be helpful when measuring optimizations. - As a convenient way to replay interactive actions that reproduce a bug. - For writing tests (although some extra functionality may be necessary in this case). Actions ======= You will notice most of the functionality is supported using the actions command line argument, this is a kind of mini-language to drive Blender. While the current set of commands is fairly limited more can be added as needed. To see a list of actions as well as their arguments run: ./blender.bin --python tests/python/bl_run_operators_event_simulate.py -- --help Examples ======== Rotate in edit-mode examples: ./blender.bin \ --factory-startup \ --enable-event-simulate \ --python tests/python/bl_run_operators_event_simulate.py \ -- \ --actions \ 'area_maximize(ui_type="VIEW_3D")' \ 'operator("object.mode_set", mode="EDIT")' \ 'operator("mesh.select_all", action="SELECT")' \ 'operator("mesh.subdivide", number_cuts=5)' \ 'operator("transform.rotate")' \ 'cursor_motion(path="CIRCLE", radius=300, steps=100, repeat=2)' Sculpt stroke: ./blender.bin \ --factory-startup \ --enable-event-simulate \ --python tests/python/bl_run_operators_event_simulate.py \ -- \ --actions \ 'area_maximize(ui_type="VIEW_3D")' \ 'event(type="FIVE", value="TAP", ctrl=True)' \ 'menu("Visual Geometry to Mesh")' \ 'menu("Frame Selected")' \ 'menu("Toggle Sculpt Mode")' \ 'event(type="WHEELDOWNMOUSE", value="TAP", repeat=2)' \ 'event(type="LEFTMOUSE", value="PRESS")' \ 'cursor_motion(path="CIRCLE", radius=300, steps=100, repeat=5)' \ 'event(type="LEFTMOUSE", value="RELEASE")' Implementation ============== While most of the operations listed above can be executed in Python directly, either the event loop won't be handled between actions (the case for typical Python script), or the context for executing the actions is not properly set (the case for timers). This utility executes actions as if the user initiated them from a key shortcut. """ import os import sys import argparse from argparse import ArgumentTypeError import bpy # ----------------------------------------------------------------------------- # Constants EVENT_TYPES = tuple(bpy.types.Event.bl_rna.properties["type"].enum_items.keys()) EVENT_VALUES = tuple(bpy.types.Event.bl_rna.properties["value"].enum_items.keys()) # `TAP` is just convenience for (`PRESS`, `RELEASE`). EVENT_VALUES_EXTRA = EVENT_VALUES + ('TAP',) # ----------------------------------------------------------------------------- # Globals # Assign a global since this script is not going to be loading new files (which would free the window). win = bpy.context.window_manager.windows[0] # ----------------------------------------------------------------------------- # Utilities def find_main_area(ui_type=None): """ Find the largest area from the current screen. """ area_best = None size_best = -1 for area in win.screen.areas: if ui_type is not None: if ui_type != area.ui_type: continue size = area.width * area.height if size > size_best: size_best = size area_best = area return area_best def gen_events_type_text(text): """ Generate events to type in `text`. """ for ch in text: kw_extra = {} # The event type in this case is ignored as only the unicode value is used for text input. type = 'SPACE' if ch == '\t': type = 'TAB' elif ch == '\n': type = 'RET' else: kw_extra["unicode"] = ch yield dict(type=type, value='PRESS', **kw_extra) kw_extra.pop("unicode", None) yield dict(type=type, value='RELEASE', **kw_extra) def repr_action(name, args, kwargs): return "%s(%s)" % ( name, ", ".join( [repr(value) for value in args] + [("%s=%r" % (key, value)) for key, value in kwargs.items()] ) ) # ----------------------------------------------------------------------------- # Simulate Events def mouse_location_get(): return ( run_event_simulate.last_event["x"], run_event_simulate.last_event["y"], ) def run_event_simulate(*, event_iter, exit_fn): """ Pass events from event_iter into Blender. """ last_event = run_event_simulate.last_event def event_step(): win = bpy.context.window_manager.windows[0] val = next(event_step.run_events, Ellipsis) if val is Ellipsis: bpy.app.use_event_simulate = False print("Finished simulation") exit_fn() return None # Run event simulation. for attr in ("x", "y"): if attr in val: last_event[attr] = val[attr] else: val[attr] = last_event[attr] # Fake event value, since press, release is so common. if val.get("value") == 'TAP': del val["value"] win.event_simulate(**val, value='PRESS') # Needed if new files are loaded. # win = bpy.context.window_manager.windows[0] win.event_simulate(**val, value='RELEASE') else: # print("val", val) win.event_simulate(**val) return 0.0 event_step.run_events = iter(event_iter) bpy.app.timers.register(event_step, first_interval=0.0, persistent=True) run_event_simulate.last_event = dict( x=win.width // 2, y=win.height // 2, ) # ----------------------------------------------------------------------------- # Action Implementations # Static methods from this class are automatically exposed as actions and included in the help text. class action_handlers: @staticmethod def area_maximize(*, ui_type=None, only_validate=False): """ ui_type: Select the area type (typically 'VIEW_3D'). Note that this area type needs to exist in the current screen. """ if not ((ui_type is None) or (isinstance(ui_type, str))): raise ArgumentTypeError("'type' argument %r not None or a string type") if only_validate: return area = find_main_area(ui_type=ui_type) if area is None: raise ArgumentTypeError("Area with ui_type=%r not found" % ui_type) x = area.x + (area.width // 2) y = area.y + (area.height // 2) yield dict(type='MOUSEMOVE', value='NOTHING', x=x, y=y) yield dict(type='SPACE', value='TAP', ctrl=True, alt=True) x = win.width // 2 y = win.height // 2 yield dict(type='MOUSEMOVE', value='NOTHING', x=x, y=y) @staticmethod def menu(text, *, only_validate=False): """ text: Menu item to search for and execute. """ if not isinstance(text, str): raise ArgumentTypeError("'text' argument not a string") if only_validate: return yield dict(type='F3', value='TAP') yield from gen_events_type_text(text) yield dict(type='RET', value='TAP') @staticmethod def event(*, type, value, ctrl=False, alt=False, shift=False, repeat=1, only_validate=False): """ type: The event, typically key, e.g. 'ESC', 'RET', 'SPACE', 'A'. value: The event type, valid values include: 'PRESS', 'RELEASE', 'TAP'. ctrl: Control modifier. alt: Alt modifier. shift: Shift modifier. """ valid_items = EVENT_VALUES_EXTRA if value not in valid_items: raise ArgumentTypeError("'value' argument %r not in %r" % (value, valid_items)) valid_items = EVENT_TYPES if type not in valid_items: raise ArgumentTypeError("'type' argument %r not in %r" % (value, valid_items)) valid_items = range(1, sys.maxsize) if repeat not in valid_items: raise ArgumentTypeError("'repeat' argument %r not in %r" % (repeat, valid_items)) del valid_items if only_validate: return for _ in range(repeat): yield dict(type=type, ctrl=ctrl, alt=alt, shift=shift, value=value) @staticmethod def cursor_motion(*, path, steps, radius=100, repeat=1, only_validate=False): """ path: The path type to use in ('CIRCLE'). steps: The number of events to generate. radius: The radius in pixels. repeat: Number of times to repeat the cursor rotation. """ import time from math import sin, cos, pi valid_items = range(1, sys.maxsize) if steps not in valid_items: raise ArgumentTypeError("'steps' argument %r not in %r" % (steps, valid_items)) valid_items = range(1, sys.maxsize) if radius not in valid_items: raise ArgumentTypeError("'radius' argument %r not in %r" % (steps, valid_items)) valid_items = ('CIRCLE',) if path not in valid_items: raise ArgumentTypeError("'path' argument %r not in %r" % (path, valid_items)) valid_items = range(1, sys.maxsize) if repeat not in valid_items: raise ArgumentTypeError("'repeat' argument %r not in %r" % (repeat, valid_items)) del valid_items if only_validate: return x_init, y_init = mouse_location_get() y_init_ofs = y_init + radius yield dict(type='MOUSEMOVE', value='NOTHING', x=x_init, y=y_init_ofs) print("\n" "Times for: %s" % os.path.basename(bpy.data.filepath)) t = time.time() step_total = 0 if path == 'CIRCLE': for _ in range(repeat): for i in range(1, steps + 1): phi = (i / steps) * 2.0 * pi x_ofs = -radius * sin(phi) y_ofs = +radius * cos(phi) step_total += 1 yield dict( type='MOUSEMOVE', value='NOTHING', x=int(x_init + x_ofs), y=int(y_init + y_ofs), ) delta = time.time() - t delta_step = delta / step_total print( "Average:", ("%.6f FPS" % (1 / delta_step)).rjust(10), ) yield dict(type='MOUSEMOVE', value='NOTHING', x=x_init, y=y_init) @staticmethod def operator(idname, *, only_validate=False, **kw): """ idname: The operator identifier (positional argument only). kw: Passed to the operator. """ # Create a temporary key binding to call the operator. wm = bpy.context.window_manager keyconf = wm.keyconfigs.user keymap_id = "Screen" key_to_map = 'F24' if only_validate: op_mod, op_submod = idname.partition(".")[0::2] op = getattr(getattr(bpy.ops, op_mod), op_submod) try: # The poll result doesn't matter we only want to know if the operator exists or not. op.poll() except AttributeError: raise ArgumentTypeError("Operator %r does not exist" % (idname)) keymap = keyconf.keymaps[keymap_id] kmi = keymap.keymap_items.new(idname=idname, type=key_to_map, value='PRESS') kmi.idname = idname props = kmi.properties for key, value in kw.items(): if not hasattr(props, key): raise ArgumentTypeError("Operator %r does not have a %r property" % (idname, key)) try: setattr(props, key, value) except Exception as ex: raise ArgumentTypeError("Operator %r assign %r property with error %s" % (idname, key, str(ex))) keymap.keymap_items.remove(kmi) return keymap = keyconf.keymaps[keymap_id] kmi = keymap.keymap_items.new(idname=idname, type=key_to_map, value='PRESS') kmi.idname = idname props = kmi.properties for key, value in kw.items(): setattr(props, key, value) yield dict(type=key_to_map, value='TAP') keymap = keyconf.keymaps[keymap_id] kmi = keymap.keymap_items[-1] keymap.keymap_items.remove(kmi) ACTION_DIR = tuple([ key for key in sorted(action_handlers.__dict__.keys()) if not key.startswith("_") ]) def handle_action(op, args, kwargs, only_validate=False): fn = getattr(action_handlers, op, None) if fn is None: raise ArgumentTypeError("Action %r is not found in %r" % (op, ACTION_DIR)) yield from fn(*args, **kwargs, only_validate=only_validate) # ----------------------------------------------------------------------------- # Argument Parsing class BlenderAction(argparse.Action): """ This class is used to extract positional & keyword arguments from a string, validate them, and return the (action, positional_args, keyword_args). All of this happens during argument parsing so any errors in the actions show useful error messages instead of failing to execute part way through. """ @staticmethod def _parse_value(value, index): """ Convert: "value(1, 2, a=1, b='', c=None)" To: ("value", (1, 2), {"a": 1, "b": "", "c": None}) """ split = value.find("(") if split == -1: op = value args = None kwargs = None else: op = value[:split] namespace = {op: lambda *args, **kwargs: (args, kwargs)} expr = value try: args, kwargs = eval(expr, namespace, namespace) except Exception as ex: raise ArgumentTypeError("Unable to parse \"%s\" at index %d, error: %s" % (expr, index, str(ex))) # Creating a list is necessary since this is a generator. try: dummy_result = list(handle_action(op, args, kwargs, only_validate=True)) except ArgumentTypeError as ex: raise ArgumentTypeError("Invalid 'action' arguments \"%s\" at index %d, %s" % (value, index, str(ex))) # Validation should never yield any events. assert not dummy_result return (op, args, kwargs) def __call__(self, parser, namespace, values, option_string=None): setattr( namespace, self.dest, [ self._parse_value(value, index) for index, value in enumerate(values) ], ) def argparse_create(): import inspect import textwrap # When --help or no args are given, print this help parser = argparse.ArgumentParser( description=__doc__, formatter_class=argparse.RawTextHelpFormatter, ) parser.add_argument( "--keep-open", dest="keep_open", default=False, action="store_true", help=( "Keep the window open instead of exiting once event simulation is complete.\n" "This can be useful to inspect the state of the file once the simulation is complete." ), required=False, ) parser.add_argument( "--time-actions", dest="time_actions", default=False, action="store_true", help=( "Display the time each action takes\n" "(useful for measuring delay between key-presses)." ), required=False, ) # Collect doc-strings from static methods in `actions`. actions_docstring = [] for action_key in ACTION_DIR: action = getattr(action_handlers, action_key) args = str(inspect.signature(action)) args = "(" + args[1:].removeprefix("*, ") args = args.replace(", *, ", ", ") # Needed in case the are positional arguments. args = args.replace(", only_validate=False", "") actions_docstring.append("- %s%s\n" % (action_key, args)) docs = textwrap.dedent((action.__doc__ or "").lstrip("\n").rstrip()) + "\n\n" actions_docstring.append(textwrap.indent(docs, " ")) parser.add_argument( "--actions", dest="actions", metavar='ACTIONS', type=str, help=( "\n" "Arguments must use one of the following prefix:\n" "\n" + "".join(actions_docstring) ), nargs='+', required=True, action=BlenderAction, ) return parser # ----------------------------------------------------------------------------- # Default Startup def setup_default_preferences(prefs): """ Set preferences useful for automation. """ prefs.view.show_splash = False prefs.view.smooth_view = 0 prefs.view.use_save_prompt = False prefs.view.show_developer_ui = True prefs.filepaths.use_auto_save_temporary_files = False # ----------------------------------------------------------------------------- # Main Function def main_event_iter(*, action_list, time_actions): """ Yield all events from action handlers. """ area = find_main_area() x_init = area.x + (area.width // 2) y_init = area.y + (area.height // 2) yield dict(type='MOUSEMOVE', value='NOTHING', x=x_init, y=y_init) if time_actions: import time t_prev = time.time() for (op, args, kwargs) in action_list: yield from handle_action(op, args, kwargs) if time_actions: t = time.time() print("%.4f: %s" % ((t - t_prev), repr_action(op, args, kwargs))) t_prev = t def main(): from sys import argv argv = argv[argv.index("--") + 1:] if "--" in argv else [] try: args = argparse_create().parse_args(argv) except ArgumentTypeError as ex: print(ex) sys.exit(1) setup_default_preferences(bpy.context.preferences) def exit_fn(): if not args.keep_open: sys.exit(0) else: bpy.app.use_event_simulate = False run_event_simulate( event_iter=main_event_iter(action_list=args.actions, time_actions=args.time_actions), exit_fn=exit_fn, ) if __name__ == "__main__": main()