API
The API is a python module named pv
that allows users to modify
the kernel’s behavior.
Properties
Properties are just variables, but they can be interpreted by the GUI and displayed properly.
- class pv.Property
Base property class.
Inherit and define:
type
: Type.set(value)
: Set the property’s value. Default just sets it, but you may need to check requirements.
Call
super().__init__()
AFTER initializingself.default
- set(value: Any) None
Sets the property’s value.
- Parameters
value – Any value. Will be casted with
self.type
.- Returns
None
- class pv.BoolProp(name: str = '', description: str = '', default: bool = False)
Boolean property.
- class pv.IntProp(name: str = '', description: str = '', default: int = 0, min: int = Ellipsis, max: int = Ellipsis)
Integer property.
- class pv.FloatProp(name: str = '', description: str = '', default: float = 0, min: float = Ellipsis, max: float = Ellipsis)
Float property.
- class pv.StrProp(name: str = '', description: str = '', default: str = '', max_len: int = 1000, choices: Sequence[str] = [])
String property.
- class pv.ListProp(name: str = '', description: str = '', default: List[Any] = [0, 0, 0, 0])
List property. Use this for color. May contain a list of lists.
A PropertyGroup is a collection of properties.
- class pv.PropertyGroup
A collection of Properties.
When creating your own PropertyGroup, you will inherit a class from this base class. Then, define:
idname
: The unique idname of this property group.properties: Define each property as a static attribute (shown below).
class MyProps(pv.PropertyGroup): prop1 = pv.props.BoolProp(name="hi")
- _get_prop(name: str) pv.props.Property
You can use this to bypass
__getattribute__
and get the actual Property object.
Data and Cache
The API has a few classes for storing and accessing data.
- class pv.DataGroup
A group of data pointers.
When creating your own DataGroup, inherit and define the idname.
Then, you can run
video.data_idname.value = x
orvideo.data_idname.value2
to access and set values.The values can be any type. Value names cannot be
idname
oritems
, as they will overwrite internal variables.
- class pv.Cache(video: None)
Cache managing for a video.
You can read and write specific file names with
cache.fp(name, mode)
, or automatically set the name to the current frame withcache.fp_frame
.To add a cache, inherit and define:
idname
: Cache idname. Will also be the cache folder name.depends
: Tuple of property idnames this cache depends on. If any of them change, the cache will be cleared. Default()
.
Operators
Operators are functions that operate on a video and can be displayed in the GUI.
- class pv.Operator(video: None)
A function that is positioned at
pv.ops.group.idname
. It can be displayed in the GUI.The return value will always be None.
To create your own operator, inherit and define:
group
: Operator group.idname
: Unique operator idname.label
: The text that will show on the GUI (as a button).description
: What this operator does.execute(video)
: This will be run when the operator is called. The first parameter is the video class (pvkernel.Video
)
Jobs
Jobs modify the rendering process.
- class pv.Job
Create a job to modify the final video.
See https://piano-video.rtfd.io/en/latest/blog/render_jobs.html for more info.
Inherit and define:
idname
: Job idname.ops
: List of operator idnames ("group.idname"
) to run.execute
: This function will run before running the operators. Default does nothing.
Utilities
- pv.utils.register_class(cls: Type) None
Register a class to “apply” it to the kernel.
- pv.utils.add_callback(func: Callable, classes: Sequence[str]) None
Add a callback function when a class is registered. The function will be passed one argument, the class.
- Parameters
func – Function to call.
classes –
A list of strings indicating which types of classes to listen for. Valid values:
”cache”: Cache
”dgroup”: DataGroup
”pgroup”: PropertyGroup
”ogroup”: Operator
- pv.utils.get(objs: Sequence[Any], idname: str) Any
Return the object in
objs
with idnameidname
.
- pv.utils.get_index(objs: Sequence[Any], idname: str) int
Return the index of the object in
objs
with idnameidname
.
- pv.utils.get_exists(objs: Sequence[Any], idname: str) bool
Check whether there is an object with idname
idname
.