Skip to content

Limitations

This page list all the current limitations of PyTVPaint in its current state.

Windows only

As stated on the homepage, the tvpaint-rpc C++ plugin is currently compiled for Windows only.

We are interested in making it available for Linux and MacOS, but being a Windows first Studio we have not needed nor had time to do so yet. If you want to contribute on this, please open an issue or a pull request on the plugin repository.

TVPaint 11.5+

TVPaint 11.5 is minimum supported version simply because we currently do not have an older version of TVPaint. The TVPaint SDK is what really limits the compatibility, but we suspect PyTVPaint is also compatible with TVPaint 11 (and perhaps even 10) since the SDK hasn't changed in a while. If you have a version of TVPaint prior to 11.5 and want to test the API, please let us know if it works and we will update the minimum requirements for the plugin and API.

Control characters in George results

Info

The latest version of PyTVPaint tries to fix this via our API, it works 90% of the time but there are still some edge cases that cannot be resolved.

This issue has been reported to TVPaint and is related to how the C++ SDK function TVSendCmd returns and encodes control character values.

If we use the George command tv_projectheadernotes for instance and the project notes text has some line breaks (\n), then the characters in the result buffer are not encoded properly.

For example:

In the project notes:

aa
bb
cc

The result from TVSendCmd:

['a', 'a', '\', 'n', 'b', 'b', '\', 'n', 'c', 'c' ]

This C++ code was used to print it:

char george_result[2048];
int executionStatus = TVSendCmd(iFilter, payload.command.c_str(), george_result);

std::stringstream ss;
ss << "[";

int i = 0;
while (george_result[i]) {
    ss << "'" << george_result[i] << "', ";
    i += 1;
}

ss << "]";

spdlog::info(ss.str());

So we suppose that control characters are not properly encoded.

Therefore, it is currently impossible to determine if it's actually a backslash \ followed by n or simply the line break character. SO PyTVPaint leaves these characters as is.

Info

The TVPaint dev team have been made aware of the issue, and we are hopeful that it will be fixed in the future.

George Official Documentation and Naming Convention Issues

Many functions in the official George documentation are poorly described or have the wrong description all together, many are overly complex and some don't work at all. Some functions also have misleading names, with some "layer" functions actually impacting the clip and not the layer for instance.

We tried to fix as many of these issues as we could when wrapping functions, putting the functions in the appropriate module when possible. We advise using our documentation for all wrapped functions instead of the official one as PyTVPaint's documentation is usually more accurate.

Misbehaving George functions

We will try to keep a list of the bugs/inconsistencies we encountered with any George commands, and describe the issues in the table below:

Method Description
tv_Ratio Always returns an empty string ("")
tv_InstanceName Crashes if we provided with an invalid layer_id
tv_CameraEnumPoints Only returns the first point, no matter how many points there are.
tv_AlphaSaveMode Extremely inconsistant, seems to only work sometimes.
tv_CameraPath Confusing arguments and seemingly incorrect results (see this)
tv_SoundClipReload Doesn't accept a proper clip id, only 0 seems to work for the current clip
tv_LayerSelectInfo Does not select frames as stated in the documentation and will also return non selected frames if attribute full is set to True
tv_ProjectSaveAudioDependencies and tv_ProjectSaveVideoDependencies Missing arguments in documentation rendering the function useless, thankfully someone provided the correct details here

TVPaint 12 Bugs and Breaking Changes:

TVPaint 12 introduces a lot of welcome changes (especially for the artists) and some new needed function for developers. However, it also introduces a lot of breaking changes and some new bugs.

To deal with these changes as well as the new functions exclusive to TVPaint 12, we added a couple decorators and functions :

Method Description
min_version_compatible When used as decorator, checks if the tvp instance making the call is above the miniumum version needed.
deprecated_warning When used as decorator, will log a warning message anytime the decorated function is called.
is_tvp_version_below_12 Returns True if the tvp instances version is below 12, False otherwise.

Below is also a list of the current breaking changes and bugs we noticed during development :

George Documentation :

  • George documentation is still not up to date and still contains many errors (seems stuck at some older TVP11 version), for now prefer the PyTVPaint documentation whenever possible.

General :

  • UI doesn't always update when values are set/updated via code, you either have to wait a few seconds for a refresh, or click somewhere else. This might lead to errors when users are using the UI at the same time.

C++ Plugin :

  • [BUG] plugin PIRF_HIDDEN_REQ and FILTERREQ_NO_TBAR don't seem to be working anymore, the plugin window is now visible and closing it kills the plugin with no way to restart it without restarting tvpaint.

Project :

  • [DEPRECATED/BREAKING] tv_ProjectInfo values of field_order have been removed so for now we provide it ourselves.
  • [BUG] tv_project_save_sequence does not render empty instances even if they exist in the timeline.

Scene :

Clip:

  • [BUG] tv_ClipSaveStructure json %fi does not work for folder structure (in v11 and v12)
  • [BUG] tv_ClipSaveStructure json seems to output low quality images, this may use the same function george.tv_save_image.

Layers :

  • [ERROR] tv_CTGGetSources is actually misspelled and is actually tv_CTGGetSource without the s at the end.
  • [ERROR] tv_CTGGetSources actually requires and returns layer Ids not names.
  • Child layers have no way of knowing if they are in a folder layer or which one.
  • A Folder layer has no way of knowing which layers are its children.
  • [BUG] Creating a CTG layer from a folder crashes TVPaint.
  • [BUG] Moving a layer that is already in a folder in the same folder crashes TVPaint.
  • tv_LayerMove can now move layers into folders but the position is relative to the root and not the folder, this is not ideal, since we can't know if a layer is already in a folder or not, which adds a lot of uncertainty when moving layers in and out of folders.
  • Not providing a FolderID to tv_LayerMove doesn't move the layer to the root, you just need to move outside the folder range for it to work, which again is pretty tough to do since we can't get the child layers of a folder and therefore their positions.
  • Moving a layer inside a folder can be done without providing a FolderID, just by moving the layer in the folder's range.
  • [BUG] CTG layer sometimes takes a while to update in the UI (a few seconds), which means they can be unintentionally edited or reset before the update.
  • CameraLayer is not really a layer and most layer functions will ignore it, prefer use of PyTVPaint Camera object instead.
  • [BUG] Selecting the Camera Layer in the UI now disables/grays out most layer related tools (this is a new behavior), this causes a lot of errors when using pipeline tools or TVPaint panels as TVPaint now raises an error messages anytime you try to use a tool that is not camera related when the camera layer is selected.
  • [BUG] tv_LayerRename does not work in TVP12 and will replace the name with an empty string, this is either a new bug or there is now a new argument that is needed but not documented.
  • [BREAKING] default layers name is now Anim_X and when these layers are queried for their names they return an empty string.
  • [BUG] tv_layer_move still sets position at (value-1) when value is superior to 0.
  • [BUG] tv_preserve_set does not seem to work in TVP12
  • [BUG] tv_LayerColor setcolor will fail when the name argument is provided.
  • [BUG] tv_LayerColor setcolor no longer returns -1 when given a bad color index.
  • [BUG] tv_layer_move no longer returns -1 when given a bad position.
  • [BUG] tv_LayerCreate should not be used when an empty string as it will consider the new variable layer_type as the name.
  • [BUG] Many layer functions that used to return -1 when given a bad layer id or position no longer do so, this can lead to silent errors and breaking behavior, this also breaks any way to check/validate these functions return values. The functions are :
    • tv_layer_set
    • tv_LayerSelection
    • tv_layer_kill
    • tv_LayerBlendingMode
    • tv_LayerStencil
    • tv_LayerPreBehavior
    • tv_LayerPostBehavior
    • tv_LayerLockPosition
    • tv_LayerMarkSet

Camera :

  • [DEPRECATED/BREAKING] Camera.anti_aliasing no longer returns anti_aliasing, for now it always returns 1.
  • [DEPRECATED/BREAKING] Camera.fps no longer returns/sets fps, now only fps is Project fps.
  • [BUG] Most Camera values can still be edited/queried using tv_CameraInfo but they are not immediately reflected in the UI, and so they can be unintentionally edited or reset.
  • [DEPRECATED/BREAKING] tv_CameraInfo values of pixel aspect ratio and fps have been "swapped" (since camera fps is no longer provided).
  • [BUG] tv_CameraInterpolation doesn't work properly in TVP12 and always returns an "empty" point.

Guidelines:

  • tv_GuidelineModify "marks" doesn't seem to work, values are never changed, added function with a warning.g_layer.tv_layer_density) now returns a float instead of an integer which broke the python cast, this is now fixed.