Commit: ce6a0ff3d86b31d75088643551fc06058a73db91 Author: Jeroen Bakker Date: Wed Dec 9 14:46:24 2020 +0100 Branches: shot-tools-development https://developer.blender.org/rBce6a0ff3d86b31d75088643551fc06058a73db91
Added more details to the design. * Added Events * Added Order of execution * Fixed spelling * Use more explicit nameing conventions =================================================================== M shot-tools/README.md =================================================================== diff --git a/shot-tools/README.md b/shot-tools/README.md index 1a8451c79a3..308cf433eb1 100644 --- a/shot-tools/README.md +++ b/shot-tools/README.md @@ -1,4 +1,4 @@ -# Project Description +# Project Description (DRAFT) Shot tools is an Add-on that helps studios to work with task specific blend-files. The main functionalities are @@ -10,12 +10,12 @@ blend-files. The main functionalities are The main design principles are: -* The tool can be installed as an add-on, but the (production specific) +* The core-tool can be installed as an add-on, but the (production specific) configuration should be part of the production repository. * The configuration files are a collection of python files. The API between - the configuration files and the add-on should be very friendly as pipeline - TD's working on the production should be able to work with it. -* TD's/artists should be able to handle issues during building without looking + the configuration files and the add-on should be easy to use as pipeline + TDs working on the production should be able to work with it. +* TDs/artists should be able to handle issues during building without looking at how the add-on is structured. * The tool contains connectors that can be configured to read/write data from the system/file that is the main location of the data. For example @@ -29,7 +29,7 @@ systems. The connectors will add flexibility to the add-on so it could be used in multiple productions or studios. In the configuration files the TD can setup the connectors that are use for -the production. There are several connectors in the add-on: +the production. Possible connectors would be: * Connector for text based config files (json/yaml). * Connector for kitsu (https://www.cg-wire.com/en/kitsu.html). @@ -49,26 +49,87 @@ there are multiple ways how to change the configuration. For any combination of these configurations hooks can be defined. -```[python] -@shot_tools.hook(asset='Spring', shot='02_020A') -fn hook_Spring_02_020A(asset: shot_tools.Asset, shot: shot_tools.Shot, **kwargs): +``` +@shot_tools.hook(match_asset_name='Spring', match_shot_code='02_020A') +def hook_Spring_02_020A(asset: shot_tools.Asset, shot: shot_tools.Shot, **kwargs) -> None: """ Specific overrides when Spring is loaded in 02_020A. """ -@shot_tools.hook(task='anim') -fn hook_task_anim(task: shot_tools.Task, shot: shot_tools.Shot, **kwargs): +@shot_tools.hook(match_task_type='anim') +def hook_task_anim(task: shot_tools.Task, shot: shot_tools.Shot, **kwargs) -> None: """ Specific overrides for any animation task. """ ``` +### Data + +All hooks will must have pythons `**kwargs` parameter. The `kwargs` contains +the context at the moment the hook is invoked. The context can contain the +following items. + +* `production`: `shot_tools.Production`: Include the name of the production + and the location on the filesystem. +* `task`: `shot_tools.Task`: The task (combination of task_type and shot) +* `task_type`: `shot_tools.TaskType`: Is part of the `task`. +* `sequence`: `shot_tools.Sequence`: Is part of `shot`. +* `shot`: `shot_tools.Shot` Is part of `task`. +* `asset`: `shot_tools.Asset`: Only available during asset loading phase. +* `asset_type`: `shot_tools.AssetType`: Only available during asset loading phase. + +### Execution Order + The add-on will internally create a list containing the hooks that needs to be executed for the command in the order what will make sense. It will then execute them one by one. -A hook can request/use needed data by simply adding a parameter. The `**kwargs` -will contain data that cannot be mapped to a parameter. +By default the next order will be used: + +* Production wide hooks +* Asset hooks +* Asset Type hooks +* Sequence hooks +* Shot hooks +* Task type hooks + +When a hook needs is defined to match an asset it will always be run when during +the asset loading phase. + +#### Events + +When order of execution can be customized by adding the optional `run_before` +or `run_after` parameters. + +``` +@shot_tools.hook(match_task_type='anim', + run_after=[shot_tools.events.AssetsLoaded()], + run_before=[shot_tools.events.ShotOverrides()]) +def hook_task_anim(task: shot_tools.Task, shot: shot_tools.Shot, **kwargs) -> None: + """ + Specific overrides for any animation task run after all assets have been loaded. + """ +``` + +Events could be: + +* `shot_tools.events.BuildStart` +* `shot_tools.events.ProductionSettingsLoaded` +* `shot_tools.events.AssetsLoaded` +* `shot_tools.events.AssetTypeOverrides` +* `shot_tools.events.SequenceOverrides` +* `shot_tools.events.ShotOverrides` +* `shot_tools.events.TaskTypeOverrides` +* `shot_tools.events.BuildFinished` +* `shot_tools.events.HookStart` +* `shot_tools.events.HookEnd` + +During usage we should see which one of these or other events are needed. + +`shot_tools.events.BuildStart`, `shot_tools.events.ProductionSettingsLoaded` +and `shot_tools.events.HookStart` can only be used in the `run_after` +parameter. `shot_tools.events.BuildFinished`, `shot_tools.events.HookFinished` +can only be used in the `run_before` parameter. ## API @@ -94,8 +155,8 @@ This API is structured/implemented in such a way that it keeps track of what the is being done. This will be used when an error occurs so a descriptive error message can be generated that would help the TD to solve the issue more quickly. The goal would be that the error messages are descriptive enough to -direct the TD into the direction where the actual cause lies. - +direct the TD into the direction where the actual cause is. And when possible +propose several solutions to fix it. ## Setting up the tool @@ -124,3 +185,15 @@ In the future other use cases will also be accessible. Use cases like: * Syncing data back from a work file to the source of the data. * Report of errors/differences between the shot file and the configuration. + +## Open Issues + +### Security + +* Security keys needed by connectors need to be stored somewhere. The easy + place is to place inside the production repository, but that isn't secure + Anyone with access to the repository could misuse the keys to access the + connector. Other solution might be to use the OS key store or retrieve the + keys from an online service authenticated by the blender cloud add-on. + + We could use `keyring` to access OS key stores. \ No newline at end of file _______________________________________________ Bf-blender-cvs mailing list [email protected] https://lists.blender.org/mailman/listinfo/bf-blender-cvs
