Coverage for core / src / sensorkit / std / enclosure.py: 100%

1# SPDX-License-Identifier: Apache-2.0 

2from typing import Literal 

3 

4from pydantic import BaseModel 

5 

6import sensorkit.api as sk 

7from sensorkit.std.traits import Deinit, Init 

8 

9 

10class EnclosureAperture(BaseModel): 

11 """Configuration for enclosure aperture opening dimensions. 

12 

13 Specifies the width (azimuth) and height (altitude) of the aperture opening to accommodate 

14 the field of view of a camera or other instrument while blocking out unwanted light sources 

15 such as the moon or other bright objects. 

16 

17 Attributes: 

18 min_azimuth_span: Minimum azimuth span (width) of the aperture opening in degrees. 

19 Defaults to 0.0 (fully closed). 

20 min_altitude_span: Minimum altitude span (height) of the aperture opening in degrees. 

21 Defaults to 0.0 (fully closed). 

22 bounds_policy: Policy for handling out-of-bounds aperture requests. "clip" will adjust 

23 the aperture to valid bounds, while "error" will raise an error. Defaults to "error". 

24 """ 

25 

26 min_azimuth_span: float = 0.0 

27 min_altitude_span: float = 0.0 

28 bounds_policy: Literal["clip", "error"] = "error" 

29 

30 

31class ControlEnclosureAperture(sk.DeviceCommand): 

32 """Move the enclosure aperture to a specified state. 

33 

34 This is the full-control command for enclosure aperture management. Only enclosures that allow 

35 custom aperture configurations will implement this command for advanced aperture control scenarios. 

36 

37 All enclosures must minimally implement OpenEnclosure and CloseEnclosure, which are 

38 limited specializations of this command for basic open/close operations. 

39 

40 Args: 

41 state: Either a predefined state ("full_open", "full_close") or a custom 

42 EnclosureAperture configuration specifying azimuth/altitude radius and bounds policy. 

43 """ 

44 

45 state: Literal["full_open", "full_close"] | EnclosureAperture = "full_open" 

46 

47 

48class OpenEnclosure(ControlEnclosureAperture): 

49 """Fully open the enclosure aperture.""" 

50 

51 state: Literal["full_open"] = "full_open" 

52 

53 

54class CloseEnclosure(ControlEnclosureAperture): 

55 """Fully close the enclosure aperture.""" 

56 

57 state: Literal["full_close"] = "full_close" 

58 

59 

60class MoveEnclosure(sk.DeviceCommand): 

61 """Rotate the enclosure and adjust its aperture to accommodate a target. 

62 

63 This command rotates the enclosure to the specified azimuth position and, if the 

64 `ControlEnclosureAperture` command is supported, centers the aperture to frame the target. 

65 This is typically used to synchronize the enclosure position with a telescope mount's pointing 

66 direction. 

67 

68 Attributes: 

69 target_azimuth: target azimuth position in degrees 

70 target_altitude: target altitude position in degrees, or None to leave unchanged 

71 """ 

72 

73 target_azimuth: float 

74 target_altitude: float | None 

75 

76 

77StandardEnclosure = sk.declare_archetype( 

78 "enclosure", 

79 required_commands=(Init, Deinit, OpenEnclosure, CloseEnclosure), 

80 optional_commands=(MoveEnclosure, ControlEnclosureAperture), 

81) 

82"""Standard enclosure archetype for observatory enclosures and domes. 

83 

84A StandardEnclosure provides basic open/close functionality and optional advanced features 

85like rotation and aperture control. All enclosures must support opening and closing operations, 

86along with initialization and deinitialization — an enclosure Init typically homes, which can 

87be slow, so it is kept distinct from connecting. Movement to specific positions and custom 

88aperture configurations are optional capabilities for more sophisticated enclosure systems. 

89"""