batgrl.gadgets.shadow_caster

A shadow caster gadget.

Module Attributes

Restrictiveness

The restrictiveness of the shadow caster.

Functions

default_light_decay(x)

Classes

ShadowCaster(*, caster_map, ...], ...)

A restrictive precise angle shadowcaster.

batgrl.gadgets.shadow_caster.Restrictiveness

The restrictiveness of the shadow caster.

Restrictiveness is one of “permissive”, “moderate”, “restrictive”.

For “permissive”, any interval is visible as long as any of it’s start, center, or end points are visible. For “moderate”, the center and either end must be visible. For “restrictive”, all points in the interval must be visible.

alias of Literal[‘permissive’, ‘moderate’, ‘restrictive’]

class batgrl.gadgets.shadow_caster.ShadowCaster(*, caster_map: ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy.uint8]], camera_pos: ~batgrl.geometry.basic.Point, camera_size: ~batgrl.geometry.basic.Size, tile_colors: list[~batgrl.colors.color_types.AColor] | None = None, light_coords: list[tuple[float, float]] | None = None, light_colors: list[~batgrl.colors.color_types.Color] | None = None, ambient_light: ~batgrl.colors.color_types.Color = (0, 0, 0), restrictiveness: ~typing.Literal['permissive', 'moderate', 'restrictive'] = 'permissive', radius: int = 20, smoothing: float = 0.3333333333333333, not_visible_blocks: bool = True, light_decay: ~collections.abc.Callable[[float], float] = <function default_light_decay>, default_color: ~batgrl.colors.color_types.AColor = (0, 0, 0, 0), alpha: float = 1.0, blitter: ~typing.Literal['braille', 'full', 'half', 'sixel'] = 'half', interpolation: ~typing.Literal['nearest', 'linear', 'cubic', 'area', 'lanczos'] = 'linear', size: ~batgrl.geometry.basic.Size = (10, 10), pos: ~batgrl.geometry.basic.Point = (0, 0), size_hint: ~batgrl.gadgets.gadget.SizeHint | None = None, pos_hint: ~batgrl.gadgets.gadget.PosHint | None = None, is_transparent: bool = True, is_visible: bool = True, is_enabled: bool = True)

Bases: Graphics

A restrictive precise angle shadowcaster.

cast_shadows() must be called to generate or update texture.

Light decay distance and radius are calculated from the point of view of the caster_map and does not depend on the size of the camera or the size of the caster. As a consequence, changing the blitter should only change the resolution of the caster.

light_coords and light_colors must be same length.

Parameters:

caster_mapNDArray[np.uint8]

A 2-d map. Non-zero values are walls.

camera_posPoint

Position of camera in map.

camera_sizeSize

Size of camera. Determines how much of the map is visible.

tile_colorslist[AColor] | None, default: None

A value n in the map will be colored tile_colors[n]. If None, tile_colors will be set to [AGRAY, AWHITE].

light_coordslist[tuple[float, float]] | None, default: None

A list of coordinates for all light sources on the map.

light_colorslist[Color] | None, default: None

A list of colors for all light sources on the map.

ambient_lightColor, default: BLACK

Color of ambient light. Default is no light.

restrictivenessRestrictiveness, default: “permissive”

Restrictiveness of casting algorithm.

radiusint, default: 20

Max visible radius from a light source.

smoothingfloat, default: 1.0 / 3.0

Smoothness of shadow edges. This value will be clamped between 0 and 1.

not_visible_blocksbool, default: True

Whether all not-visible cells will be treated as opaque.

light_decayCallable[[float], float], default: default_light_decay

The strength of light as a function of distance from light origin. The default decay is 1 / distance.

default_colorAColor, default: AColor(0, 0, 0, 0)

Default texture color.

alphafloat, default: 1.0

Transparency of gadget.

interpolationInterpolation, default: “linear”

Interpolation used when gadget is resized.

blitterBlitter, default: “half”

Determines how graphics are rendered.

sizeSize, default: Size(10, 10)

Size of gadget.

posPoint, default: Point(0, 0)

Position of upper-left corner in parent.

size_hintSizeHint | None, default: None

Size as a proportion of parent’s height and width.

pos_hintPosHint | None, default: None

Position as a proportion of parent’s height and width.

is_transparentbool, default: True

Whether gadget is transparent.

is_visiblebool, default: True

Whether gadget is visible. Gadget will still receive input events if not visible.

is_enabledbool, default: True

Whether gadget is enabled. A disabled gadget is not painted and doesn’t receive input events.

Attributes:

caster_mapNDArray[np.uint8]

A 2-d map. Non-zero values are walls.

camera_posPoint

Position of camera in map.

camera_sizeSize

Size of camera. Determines how much of the map is visible.

tile_colorslist[AColor]

A value n in the map will be colored tile_colors[n].

light_coordslist[tuple[float, float]] | None

A list of coordinates for all light sources on the map.

light_colorslist[Color] | None

A list of colors for all light sources on the map.

ambient_lightColor

Color of ambient light.

restrictivenessRestrictiveness

Restrictiveness of casting algorithm.

radiusint

Max visible radius from a light source.

smoothingfloat

Smoothness of shadow edges.

not_visible_blocksbool

Whether all not-visible cells will be treated as opaque.

light_decayCallable[[float], float]

The strength of light as a function of distance from origin.

textureNDArray[np.uint8]

uint8 RGBA color array.

default_colorAColor

Default texture color.

alphafloat

Transparency of gadget.

interpolationInterpolation

Interpolation used when gadget is resized.

blitterBlitter

Determines how graphics are rendered.

sizeSize

Size of gadget.

heightint

Height of gadget.

rowsint

Height of gadget.

widthint

Width of gadget.

columnsint

Width of gadget.

posPoint

Position relative to parent.

topint

y-coordinate of top of gadget.

yint

y-coordinate of top of gadget.

leftint

x-coordinate of left side of gadget.

xint

x-coordinate of left side of gadget.

bottomint

y-coordinate of bottom of gadget.

rightint

x-coordinate of right side of gadget.

centerPoint

Position of center of gadget.

absolute_posPoint

Absolute position on screen.

size_hintSizeHint

Gadget’s size as a proportion of its parent’s size.

pos_hintPosHint

Gadget’s position as a proportion of its parent’s size.

parent: Gadget | None

Parent gadget.

childrenlist[Gadget]

Children gadgets.

is_transparentbool

Whether gadget is transparent.

is_visiblebool

Whether gadget is visible.

is_enabledbool

Whether gadget is enabled.

rootGadget | None

Return the root gadget if connected to gadget tree.

appApp

The running app.

Methods

cast_shadows()	Update texture by shadow casting all light sources.
to_map_coords(point)	Convert a point in the gadget’s local coordinates to a point in the map’s coordinates.
to_png(path)	Write texture to provided path as a png image.
clear()	Fill texture with default color.
apply_hints()	Apply size and pos hints.
to_local(point)	Convert point in absolute coordinates to local coordinates.
collides_point(point)	Return true if point collides with visible portion of gadget.
collides_gadget(other)	Return true if other is within gadget’s bounding box.
pull_to_front()	Move to end of gadget stack so gadget is drawn last.
walk()	Yield all descendents of this gadget (preorder traversal).
walk_reverse()	Yield all descendents of this gadget (reverse postorder traversal).
ancestors()	Yield all ancestors of this gadget.
add_gadget(gadget)	Add a child gadget.
add_gadgets(*gadgets)	Add multiple child gadgets.
remove_gadget(gadget)	Remove a child gadget.
prolicide()	Recursively remove all children.
destroy()	Remove this gadget and recursively remove all its children.
bind(prop, callback)	Bind callback to a gadget property.
unbind(uid)	Unbind a callback from a gadget property.
tween(…)	Sequentially update gadget properties over time.
on_size()	Update gadget after a resize.
on_transparency()	Update gadget after transparency is enabled/disabled.
on_add()	Update gadget after being added to the gadget tree.
on_remove()	Update gadget after being removed from the gadget tree.
on_key(key_event)	Handle a key press event.
on_mouse(mouse_event)	Handle a mouse event.
on_paste(paste_event)	Handle a paste event.
on_terminal_focus(focus_event)	Handle a focus event.

property absolute_pos: Point

Absolute position on screen.

add_gadget(gadget: Gadget) → None

Add a child gadget.

Parameters:

gadgetGadget

A gadget to add as a child.

add_gadgets(*gadgets: Gadget) → None

Add multiple child gadgets.

Parameters:

*gadgetsGadget

Gadgets to add as children. Can also accept a single iterable of gadgets.

property alpha: float

Transparency of gadget.

ancestors() → Iterator[Gadget]

Yield all ancestors of this gadget.

Yields:

Gadget

An ancestor of this gadget.

property app

The running app.

apply_hints() → None

Apply size and pos hints.

This is called automatically when the gadget is added to the gadget tree and when the gadget’s parent’s size changes.

bind(prop: str, callback: Callable[[], None]) → int

Bind callback to a gadget property. When the property is updated, callback is called with no arguments.

Parameters:

propstr

The name of the gadget property.

callbackCallable[[], None]

Callback to bind to property.

Returns:

int

A unique id used to unbind the callback.

property blitter: Literal['braille', 'full', 'half', 'sixel']

Determines how graphics are rendered.

property bottom: int

y-coordinate of bottom of gadget.

cast_shadows()

Update texture by shadow casting all light sources.

property center: Point

Position of center of gadget.

children: _GadgetList

The gadget’s children.

clear() → None

Fill texture with default color.

collides_gadget(other: Gadget) → bool

Return true if other is within gadget’s bounding box.

Parameters:

otherGadget

Another gadget.

Returns:

bool

Whether other collides with gadget.

collides_point(point: Point) → bool

Return true if point collides with visible portion of gadget.

Parameters:

pointPoint

A point.

Returns:

bool

Whether point collides with gadget.

property columns: int

Width of gadget.

destroy() → None

Remove this gadget and recursively remove all its children.

dispatch_key(key_event: KeyEvent) → bool | None

Dispatch a key press event until handled.

A key press event is handled if a handler returns True.

Parameters:

key_eventKeyEvent

The key event to dispatch.

Returns:

bool | None

Whether the dispatch was handled.

dispatch_mouse(mouse_event: MouseEvent) → bool | None

Dispatch a mouse event until handled.

A mouse event is handled if a handler returns True.

Parameters:

mouse_eventMouseEvent

The mouse event to dispatch.

Returns:

bool | None

Whether the dispatch was handled.

dispatch_paste(paste_event: PasteEvent) → bool | None

Dispatch a paste event until handled.

A paste event is handled if a handler returns True.

Parameters:

paste_eventPasteEvent

The paste event to dispatch.

Returns:

bool | None

Whether the dispatch was handled.

dispatch_terminal_focus(focus_event: FocusEvent) → bool | None

Dispatch a focus event until handled.

A focus event is handled if a handler returns True.

Parameters:

focus_eventFocusEvent

The focus event to dispatch.

Returns:

bool | None

Whether the dispatch was handled.

property height: int

Height of gadget.

property interpolation: Literal['nearest', 'linear', 'cubic', 'area', 'lanczos']

Interpolation used when gadget is resized.

property is_enabled: bool

Whether gadget is enabled. A disabled gadget is not painted and doesn’t receive input events.

property is_transparent: bool

Whether gadget is transparent.

property is_visible: bool

Whether gadget is visible. Gadget will still receive input events if not visible.

property left: int

x-coordinate of left side of gadget.

on_add() → None

Resize if geometry is incorrect on add.

on_key(key_event: KeyEvent) → bool | None

Handle a key press event.

Handled key presses should return True.

Parameters:

key_eventKeyEvent

The key event to handle.

Returns:

bool | None

Whether the key event was handled.

on_mouse(mouse_event: MouseEvent) → bool | None

Handle a mouse event.

Handled mouse events should return True.

Parameters:

mouse_eventMouseEvent

The mouse event to handle.

Returns:

bool | None

Whether the mouse event was handled.

on_paste(paste_event: PasteEvent) → bool | None

Handle a paste event.

Handled paste events should return True.

Parameters:

paste_eventPasteEvent

The paste event to handle.

Returns:

bool | None

Whether the paste event was handled.

on_remove() → None

Update gadget after being removed from the gadget tree.

on_size()

Resize texture and _light_intensity buffer on size.

on_terminal_focus(focus_event: FocusEvent) → bool | None

Handle a focus event.

Handled focus events should return True.

Parameters:

focus_eventFocusEvent

The focus event to handle.

Returns:

bool | None

Whether the focus event was handled.

on_transparency() → None

Update gadget after transparency is enabled/disabled.

parent: Gadget | None

The gadget’s parent.

property pos: Point

Position relative to parent.

property pos_hint: PosHint

Gadget’s position as a proportion of its parent’s size.

prolicide() → None

Recursively remove all children.

pull_to_front() → None

Move gadget to end of gadget stack so that it is drawn last.

remove_gadget(gadget: Gadget) → None

Remove a child gadget.

Parameters:

gadgetGadget

The gadget to remove from children.

property right: int

x-coordinate of right side of gadget.

property root: _Root | None

Return the root gadget if connected to gadget tree.

property rows: int

Height of gadget.

property size: Size

Size of gadget.

property size_hint: SizeHint

Gadget’s size as a proportion of its parent’s size.

to_local(point: Point) → Point

Convert point in absolute coordinates to local coordinates.

Parameters:

pointPoint

Point in absolute (screen) coordinates.

Returns:

Point

The point in local coordinates.

to_map_coords(point: Point) → tuple[float, float]

Convert a point in the gadget’s local coordinates to a point in the map’s coordinates.

Parameters:

pointPoint

Point in local coordinates.

Returns:

tuple[float, float]

The coordinates of the point in the map.

to_png(path: Path) → None

Write texture to provided path as a png image.

property top: int

y-coordinate of top of gadget.

async tween(*, duration: float = 1.0, easing: Literal['linear', 'in_quad', 'out_quad', 'in_out_quad', 'in_cubic', 'out_cubic', 'in_out_cubic', 'in_quart', 'out_quart', 'in_out_quart', 'in_quint', 'out_quint', 'in_out_quint', 'in_sine', 'out_sine', 'in_out_sine', 'in_exp', 'out_exp', 'in_out_exp', 'in_circ', 'out_circ', 'in_out_circ', 'in_elastic', 'out_elastic', 'in_out_elastic', 'in_back', 'out_back', 'in_out_back', 'in_bounce', 'out_bounce', 'in_out_bounce'] = 'linear', on_start: Callable[[], None] | None = None, on_progress: Callable[[float], None] | None = None, on_complete: Callable[[], None] | None = None, **properties: Real | ndarray[tuple[int, ...], dtype[number]] | Sequence[Real] | PosHint | SizeHint) → None

Coroutine that sequentially updates gadget properties over a duration (in seconds).

Parameters:

durationfloat, default: 1.0

The duration of the tween in seconds.

easingEasing, default: “linear”

The easing used for tweening.

on_startCallable[[], None] | None, default: None

Called when tween starts.

on_progressCallable[[float], None] | None, default: None

Called as tween updates with current progress.

on_completeCallable[[], None] | None, default: None

Called when tween completes.

**propertiesReal | NDArray[np.number] | Sequence[Real] | PosHint | SizeHint

Gadget properties’ target values. E.g., to smoothly tween a gadget’s position to (5, 10) over 2.5 seconds, specify the pos property as a keyword-argument: await gadget.tween(pos=(5, 10), duration=2.5, easing="out_bounce")

Warning

Running several tweens on the same properties concurrently will probably result in unexpected behavior.

Notes

Tweened values will be coerced to match the type of the initial value of their corresponding property.

Non-numeric values will be set immediately.

unbind(uid: int) → None

Unbind a callback from a gadget property.

Parameters:

uidint

Unique id returned by the bind() method.

walk() → Iterator[Gadget]

Yield all descendents of this gadget (preorder traversal).

Yields:

Gadget

A descendent of this gadget.

walk_reverse() → Iterator[Gadget]

Yield all descendents of this gadget (reverse postorder traversal).

Yields:

Gadget

A descendent of this gadget.

property width: int

Width of gadget.

property x: int

x-coordinate of left side of gadget.

property y: int

y-coordinate of top of gadget.

batgrl.gadgets.shadow_caster.default_light_decay(x: float) → float