Objects Placement

isa_manim.isa_scene.isa_placement.IsaPlacementMap provides the data structures and function interfaces for object placement. The primary of IsaPlacementMap contains:

_placement_object_dict provides one dictionary of objects in the scene. The dictionary key can be an integer or string. The value of the dictionary is an entity of isa_manim.isa_scene.isa_placement.IsaPlacementItem. The data structure provides the position information of one object.
_placement_map presents the placement map as a 2-D array of an integer. Each element in the array presents the status of one single square of the grid.

IsaPlacementMap provides several groups of APIs to operate the dictionary and the map. At first, has_object and get_object are used to operate the placement dictionary. has_object checks whether one specified hash exists in the dictionary, and get_object returns the object associated with the specified hash.

Then, place_object adds one single object to the placement map, and place_object_group adds a group of objects to the placement map. These two functions call place_placement_item to find an appropriate space to place objects.

The following functions return the status of the placement map:

get_placement_width and get_placement_height returns the width and height of the actual occupied map. Only occupied columns/rows or margins are counted.
get_placement_origin returns the central position of the placement map.
get_camera_scale returns the scale factor of the placement to fit into a specified camera. The value provided by this camera is used to show all objects in the scene by scaling the camera.
dump_placement returns a string to present the placement for debugging.

The following functions operate on the placement map. reset_placement removes all placed objects and resizes the placement map to the initialization size. resize_placement resizes the placement map to a specified size while keeping all placed objects.

Flow charts

The flow charts to add one single object in the placement map:

flowchart LR

subgraph place_object
A1[Get align row if necessary]
A2[Create a placement item]
A3[Add item to the placement dictionary]
A4[End]

A1-->A2-->A3==>B1

subgraph place_placement_item
B1[Try to place item into the placement map]
B2{Placement success}
B3[Mark the item in the placement map]
B4[Resize the placement with a fix h/w ratio]
end

B1-->B2
B2--"Yes"-->B3==>A4
B2--"No"-->B4-->B1

end

The flow graph to add one group of objects in the placement map:

flowchart LR

subgraph place_object_group
A1[Create placement items]
A2[Convert the object group to a object matrix]
A3[Create place holder for the entire group]
A4[Add each item in the group to the dictionary and map]
A5[End]

A1==>C1
A2-->A3==>B1
A4-->A5

subgraph place_placement_item
B1[Try to place item into the placement map]
B2{Placement success}
B3[Mark the item in the placement map]
B4[Resize the placement with a fix h/w ratio]
end

B1-->B2
B2--"Yes"-->B3==>A4
B2--"No"-->B4-->B1

subgraph Get suitable shape of objects
C1{h/w ratio is fix?}
C2[Take fixed h/w ratio as the shape of the object group]
C3[Count the width and the height of all objects in one row including marigins]
C4{if the h/w ratio is larger than the ratio of scene}
C5[Double the elements in the shape]
C6[Take this h/w ratio as the shape of the object group]

C1--"Yes"-->C2==>A2
C1--"No"-->C3-->C4
C4--"Yes"-->C5-->C3
C4--"No"-->C6==>A2
end

end

IsaPlacementItem

Data structure of one object for auto placement.

Attributes:

Name	Type	Description
`isa_object`	`Mobject`	Isa object, RegUnit, ElemUnit, FunctionUnit and MemoryUnit.
`isa_hash`	`Union[int, str]`	Hash value of this object.
`row`	`int`	Vertical ordinate of left-up corner.
`col`	`int`	Horizontal ordinate of left-up corner.

`init(isa_object, isa_hash)`

Construct one data structure for animate.

Parameters:

Name	Type	Description	Default
`isa_object`	`Mobject`	Isa object.	required
`isa_hash`	`Union[int, str]`	Hash value of this object.	required

`get_height()`

Return the height of this object for placement. The height is ceil to an integer.

Returns:

Type	Description
`int`	The height of this object.

`get_marker()`

Return the marker of this object for placement.

Returns:

Type	Description
`int`	Marker of this object.

`get_width()`

Return the width of this object for placement. The width is ceil to an integer.

Returns:

Type	Description
`int`	The width of this object.

`set_corner(row, col)`

Set the position of object by the left-up corner position. Move object to the specified position.

Parameters:

Name	Type	Description	Default
`row`	`int`	Vertical ordinate of left-up corner.	required
`col`	`int`	Horizontal ordinate of left-up corner.	required

IsaPlacementMap

This class manages the position of objects in scene.

Attributes:

Name	Type	Description
`_placement_object_dict`	`Dict[str, IsaPlacementItem]`	Dictionary of objects, key is one hash value and the value is item of IsaPlacementItem.
`_placement_map`	`List[List[int]]`	Array of the placement.
`_placement_width`	`int`	Width of the placement.
`_placement_height`	`int`	Height of the placement.
`_placement_hv_ratio`	`float`	height/width ratio of the placement.
`_placement_strategy`	`str`	Strategy to find rectangle.

`init(strategy='RB')`

Initialize placement map.

Parameters:

Name	Type	Description	Default
`strategy`	`str`	Strategy to search rectangle, option: RB or BR.	`'RB'`

`dump_placement()`

Return a string of placement map for debug.

Returns:

Type	Description
`str`	A string of placement map.

`get_camera_scale(camera_width, camera_height)`

Return scale factor of the placement to fit into specified camera.

Parameters:

Name	Type	Description	Default
`camera_width`	`float`	The width of camera.	required
`camera_height`	`float`	The height of camera.	required

Returns:

Type	Description
`float`	Scale factor of the camera.

`get_object(place_hash)`

Return ISA object of the specified hash.

Parameters:

Name	Type	Description	Default
`place_hash`	`str`	Hash value of ISA object.	required

Returns:

Type	Description
`Mobject`	The object for the specified ISA.

`get_object_group(place_hash)`

Return a list of object with prefix hash.

Parameters:

Name	Type	Description	Default
`place_hash`	`str`	Hash value of ISA object.	required

Returns:

Type	Description
`List[Mobject]`	A list of objects for the specified ISA.

`get_placement_height()`

Return the height of the placement, only occupied rows or margins are count.

Returns:

Type	Description
`int`	Return the width of the placement map.

`get_placement_origin()`

Return center position of the placement map related to the left-up corner.

Returns:

Type	Description
`array`	Return the center position of the placement map.

`get_placement_width()`

Return the width of the placement, only occupied column or margins are count.

Returns:

Type	Description
`int`	Return the width of the placement map.

`has_object(place_hash)`

Check whether the object is existed.

Parameters:

Name	Type	Description	Default
`place_hash`	`str`	Hash value of ISA object.	required

Returns:

Type	Description
`bool`	True means the hash exists in the placement dictionary.

`has_object_group(place_hash)`

Check whether there is object with prefix.

Parameters:

Name	Type	Description	Default
`place_hash`	`str`	Hash value of ISA object.	required

Returns:

Type	Description
`bool`	True means the hash as prefix exists in the placement dictionary.

`place_object(place_object, place_hash, align_with=None)`

Add object into the dictionary and place it into the placement map.

Parameters:

Name	Type	Description	Default
`place_object`	`Mobject`	Object to place.	required
`place_hash`	`Union[int, str]`	Hash value of ISA object.	required
`align_with`	`Mobject`	The object will be placed at the same row with another object.	`None`

`place_object_group(place_object_list, place_hash_list, force_hw_ratio=None)`

Add a group of object into the dictionary and place it into the placement map.

Parameters:

Name	Type	Description	Default
`place_object_list`	`List[Mobject]`	List of object to place.	required
`place_hash_list`	`List[Union[int, str]]`	Hash value of ISA object.	required
`force_hw_ratio`	`Union[int, None]`	Force the horization/vertical ratio of the groups.	`None`

`place_placement_item(placement_item, force=False, align_row=None)`

Place one item into the placement map.

This function tries to allocate the item into the placement map. If placement fails, this function will resize the placement map and try again. This function continues iteration until the object can be allocated into the placement map.

Parameters:

Name	Type	Description	Default
`placement_item`	`IsaPlacementItem`	Object item to place in the map.	required
`force`	`bool`	True means the object item must place at the position specified in `placement_item`.	`False`
`align_row`	`int`	The object item must be specified at the specified row.	`None`

`reset_placement(keep_objects=None, keep_pos=True)`

Reset placement map.

Parameters:

Name	Type	Description	Default
`keep_objects`	`List[Mobject]`	Objects should keep in the scene.	`None`
`keep_pos`	`bool`	True means keep the position of keep objects in the new placement.	`True`

`resize_placement(new_width, new_height)`

Resize placement map while keeping items in the old placement map.

Parameters:

Name	Type	Description	Default
`new_width`	`int`	New width of the placement map.	required
`new_height`	`int`	New height of the placement map.	required

Objects Placement

Flow charts

IsaPlacementItem

__init__(isa_object, isa_hash)

get_height()

get_marker()

get_width()

set_corner(row, col)

IsaPlacementMap

__init__(strategy='RB')

dump_placement()

get_camera_scale(camera_width, camera_height)

get_object(place_hash)

get_object_group(place_hash)

get_placement_height()

get_placement_origin()

get_placement_width()

has_object(place_hash)

has_object_group(place_hash)

place_object(place_object, place_hash, align_with=None)

place_object_group(place_object_list, place_hash_list, force_hw_ratio=None)

place_placement_item(placement_item, force=False, align_row=None)

reset_placement(keep_objects=None, keep_pos=True)

resize_placement(new_width, new_height)

`init(isa_object, isa_hash)`

`get_height()`

`get_marker()`

`get_width()`

`set_corner(row, col)`

`init(strategy='RB')`

`dump_placement()`

`get_camera_scale(camera_width, camera_height)`

`get_object(place_hash)`

`get_object_group(place_hash)`

`get_placement_height()`

`get_placement_origin()`

`get_placement_width()`

`has_object(place_hash)`

`has_object_group(place_hash)`

`place_object(place_object, place_hash, align_with=None)`

`place_object_group(place_object_list, place_hash_list, force_hw_ratio=None)`

`place_placement_item(placement_item, force=False, align_row=None)`

`reset_placement(keep_objects=None, keep_pos=True)`

`resize_placement(new_width, new_height)`