component¶

Warning

This section covers the implementations of JAnim, which may be quite complex. If you do not have the need to delve into the source code, you may choose to read it at your discretion.

class janim.components.component.CheckComponentMethods(name: str, bases: tuple[type, ...], attrdict: dict, *, impl=False)¶

Bases: type

All subclasses of Component are checked to ensure that they implement the copy, _become, and not_changed methods.

Meaning:

copy:

Calling this function produces a copy of the component.

In this function, cmpt_copy = super().copy() should be used to obtain a copy of the component. The relevant copying operations should then be performed on this object, and finally the cmpt_copy object should be returned.
_become:

Takes another component as an argument (most likely one of the same type; this behavior is not yet stable and may be clarified in the future).

In this function, super()._become(other) should first be used to handle the parent class’s logic (if it exists). The current component’s logic should then be handled, ultimately ensuring that the current component’s data matches that of the target component.
not_changed:

This function should return a bool indicating whether it can be determined that the component’s data has not changed, and is used to detect modifications to the component.

For example, when the _points data of Cmpt_Points has not been modified, the id of its underlying NumPy array remains unchanged. After the data is modified, however, it becomes a completely different NumPy array with a different id.

Therefore, Cmpt_Points returns False whenever its underlying NumPy arrays cannot be determined to be the same using is (even if the data has been modified and then changed back to the same values, it will still return False).

Additionally, for components that do not contain any additional data and only provide additional methods, impl=True can be used to skip the check for that subclass.

class janim.components.component.Component¶

Bases: Generic

class BindInfo(decl_cls: type[Item], at_item: Item, key: str, _computed_caches: dict[relation.FlagHandle, Any] = <factory>)¶

Bases: object

Encapsulation of component definition information

Parameters:

decl_cls – The class in which it is declared in the form xxx = CmptInfo(...); if both a class and its parent class have xxx = CmptInfo(...), then decl_cls is the parent class.
at_item – The item object to which this component object is currently bound
key – The variable name of this component object within the item

For example:

class MyCmpt(Component): ...

class MyItem(Item):
    cmpt1 = CmptInfo(MyCmpt[Self])
    cmpt2 = CmptInfo(MyCmpt[Self])

class MyItem2(MyItem):
    cmpt3 = CmptInfo(MyCmpt[Self])

item = MyItem()

# item.cmpt1.bind_info is consistent with BindInfo(MyItem, item, 'cmpt1')
# item.cmpt2.bind_info is consistent with BindInfo(MyItem, item, 'cmpt2')

item2 = MyItem2()

# item2.cmpt1.bind_info is consistent with BindInfo(MyItem, item2, 'cmpt1')
# item2.cmpt3.bind_info is consistent with BindInfo(MyItem2, item2, 'cmpt3')

decl_cls: type[Item]¶

at_item: Item¶

key: str¶

get_computed_for(flag_handle: FlagHandle) → Any | Expired¶

mark_computed_for(flag_handle: FlagHandle, data: Any) → None¶

reset_computed_for(flag_handle: FlagHandle) → None¶

reset_computed_for_func(func: Callable) → None¶

reset_computed_for_list(lst: list[FlagHandle]) → None¶

reset_computed_for_all() → None¶

init_bind(bind: BindInfo) → None¶

Used for Item._init_components

Subclasses can inherit this function to perform item-related processing

copy() → Self¶

become(other) → Self¶

not_changed(other) → bool¶

get_same_cmpt(item: Item, *, use_mock: bool = False, create_mock: Literal[False]) → Self | None¶

get_same_cmpt(item: Item, *, use_mock: bool = False, create_mock: Literal[True] = True) → Self

Get the component in the item object with the same self.bind.key as this component. By default, a mock will be created if necessary.

Note: If self.bind is invalid, an attribute error will be raised when attempting to access an attribute of None. However, this is not checked within the function; if necessary, the intended approach is to perform the check outside the function.

Parameters:

item – The item from which to get the component
use_mock – Whether a previously created mock can be used when the corresponding component is unavailable
create_mock – Whether to create a mock based on astype() when the corresponding component is unavailable

Returns:

The resulting component; may return None if create_mock=False

walk_same_cmpt_of_self_and_descendants(root_only: bool = False, *, use_mock: bool = False, create_mock: bool = False, unordered: bool = False) → Iterable[Self]¶

Traverse this component and the corresponding components in the descendant items of its containing item. By default, no mocks are created.

If root_only is set or self.bind is invalid, descendant components are ignored.

Parameters:: root_only – Whether to ignore descendant components and only yield this component

For the remaining parameters, see the documentation for walk_same_cmpt_of_descendants().

walk_same_cmpt_of_descendants(*, use_mock: bool = False, create_mock: bool = False, unordered: bool = False) → Iterable[Self]¶

Traverse the corresponding components in the descendant items of the containing item. By default, no mocks are created.

Parameters:

use_mock – Whether a previously created mock can be used when the corresponding component is unavailable
create_mock – Whether to create a mock based on astype() when the corresponding component is unavailable
unordered – Whether to allow traversal without guaranteeing order. If specified, performance may be better for complex structures.

property r: ItemT¶: The item it resides in, facilitating chained calls to other components within the same item.

classmethod align_for_interpolate(cmpt1, cmpt2) → AlignedData[Self]¶

interpolate(cmpt1, cmpt2, alpha: float, *, path_func=None) → None¶

class janim.components.component.CmptInfo(cls: type[T], *args, **kwargs)¶

Bases: Generic

When defining components in a class, you should use this class to wrap

For example:

class MyItem(Item):
    # Wrong!
    # cmpt1 = MyCmpt()

    # Correct
    cmpt1 = CmptInfo(MyCmpt[Self])

    # Wrong
    # cmpt2 = MyCmptWithArgs(1)

    # Correct
    cmpt2 = CmptInfo(MyCmptWithArgs[Self], 1)

create() → Component¶

janim.components.component.CmptGroup(*cmpt_info_list: CmptInfo) → CmptInfo¶

Used to package multiple components, allowing them to be called simultaneously

For example:

class MyItem(Item):
    stroke = CmptInfo(Cmpt_Rgbas[Self])
    fill = CmptInfo(Cmpt_Rgbas[Self])
    color = CmptGroup(stroke, fill)

item = MyItem()
item.stroke.set(...)    # Only the method of stroke be called
item.color.set(...)     # the methods of stroke and fill are both called