photonlibpy 2025.0.0b3__py3-none-any.whl → 2025.0.0b4__py3-none-any.whl

photonlibpy/simulation/visionSystemSim.py

@@ -15,7 +15,22 @@ from .visionTargetSim import VisionTargetSim
 
 
 class VisionSystemSim:
+    """A simulated vision system involving a camera(s) and coprocessor(s) mounted on a mobile robot
+    running PhotonVision, detecting targets placed on the field. :class:`.VisionTargetSim`s added to
+    this class will be detected by the :class:`.PhotonCameraSim`s added to this class. This class
+    should be updated periodically with the robot's current pose in order to publish the simulated
+    camera target info.
+    """
+
     def __init__(self, visionSystemName: str):
+        """A simulated vision system involving a camera(s) and coprocessor(s) mounted on a mobile robot
+        running PhotonVision, detecting targets placed on the field. :class:`.VisionTargetSim`s added to
+        this class will be detected by the :class:`.PhotonCameraSim`s added to this class. This class
+        should be updated periodically with the robot's current pose in order to publish the simulated
+        camera target info.
+
+        :param visionSystemName: The specific identifier for this vision system in NetworkTables.
+        """
         self.dbgField: Field2d = Field2d()
         self.bufferLength: seconds = 1.5
 
@@ -32,12 +47,21 @@ class VisionSystemSim:
         wpilib.SmartDashboard.putData(self.tableName + "/Sim Field", self.dbgField)
 
     def getCameraSim(self, name: str) -> PhotonCameraSim | None:
+        """Get one of the simulated cameras."""
         return self.camSimMap.get(name, None)
 
     def getCameraSims(self) -> list[PhotonCameraSim]:
+        """Get all the simulated cameras."""
         return [*self.camSimMap.values()]
 
     def addCamera(self, cameraSim: PhotonCameraSim, robotToCamera: Transform3d) -> None:
+        """Adds a simulated camera to this vision system with a specified robot-to-camera transformation.
+        The vision targets registered with this vision system simulation will be observed by the
+        simulated :class:`.PhotonCamera`.
+
+        :param cameraSim:     The camera simulation
+        :param robotToCamera: The transform from the robot pose to the camera pose
+        """
         name = cameraSim.getCamera().getName()
         if name not in self.camSimMap:
             self.camSimMap[name] = cameraSim
@@ -49,10 +73,15 @@ class VisionSystemSim:
             )
 
     def clearCameras(self) -> None:
+        """Remove all simulated cameras from this vision system."""
         self.camSimMap.clear()
         self.camTrfMap.clear()
 
     def removeCamera(self, cameraSim: PhotonCameraSim) -> bool:
+        """Remove a simulated camera from this vision system.
+
+        :returns: If the camera was present and removed
+        """
         name = cameraSim.getCamera().getName()
         if name in self.camSimMap:
             del self.camSimMap[name]
@@ -65,6 +94,14 @@ class VisionSystemSim:
         cameraSim: PhotonCameraSim,
         time: seconds = wpilib.Timer.getFPGATimestamp(),
     ) -> Transform3d | None:
+        """Get a simulated camera's position relative to the robot. If the requested camera is invalid, an
+        empty optional is returned.
+
+        :param cameraSim:   The specific camera to get the robot-to-camera transform of
+        :param timeSeconds: Timestamp in seconds of when the transform should be observed
+
+        :returns: The transform of this camera, or an empty optional if it is invalid
+        """
         if cameraSim in self.camTrfMap:
             trfBuffer = self.camTrfMap[cameraSim]
             sample = trfBuffer.sample(time)
@@ -80,6 +117,13 @@ class VisionSystemSim:
         cameraSim: PhotonCameraSim,
         time: seconds = wpilib.Timer.getFPGATimestamp(),
     ) -> Pose3d | None:
+        """Get a simulated camera's position on the field. If the requested camera is invalid, an empty
+        optional is returned.
+
+        :param cameraSim: The specific camera to get the field pose of
+
+        :returns: The pose of this camera, or an empty optional if it is invalid
+        """
         robotToCamera = self.getRobotToCamera(cameraSim, time)
         if robotToCamera is None:
             return None
@@ -93,6 +137,14 @@ class VisionSystemSim:
     def adjustCamera(
         self, cameraSim: PhotonCameraSim, robotToCamera: Transform3d
     ) -> bool:
+        """Adjust a camera's position relative to the robot. Use this if your camera is on a gimbal or
+        turret or some other mobile platform.
+
+        :param cameraSim:     The simulated camera to change the relative position of
+        :param robotToCamera: New transform from the robot to the camera
+
+        :returns: If the cameraSim was valid and transform was adjusted
+        """
         if cameraSim in self.camTrfMap:
             self.camTrfMap[cameraSim].addSample(
                 wpilib.Timer.getFPGATimestamp(), Pose3d() + robotToCamera
@@ -102,6 +154,7 @@ class VisionSystemSim:
             return False
 
     def resetCameraTransforms(self, cameraSim: PhotonCameraSim | None = None) -> None:
+        """Reset the transform history for this camera to just the current transform."""
         now = wpilib.Timer.getFPGATimestamp()
 
         def resetSingleCamera(self, cameraSim: PhotonCameraSim) -> bool:
@@ -133,12 +186,30 @@ class VisionSystemSim:
     def addVisionTargets(
         self, targets: list[VisionTargetSim], targetType: str = "targets"
     ) -> None:
+        """Adds targets on the field which your vision system is designed to detect. The {@link
+        PhotonCamera}s simulated from this system will report the location of the camera relative to
+        the subset of these targets which are visible from the given camera position.
+
+        :param targets: Targets to add to the simulated field
+        :param type:    Type of target (e.g. "cargo").
+        """
+
         if targetType not in self.targetSets:
             self.targetSets[targetType] = targets
         else:
             self.targetSets[targetType] += targets
 
     def addAprilTags(self, layout: AprilTagFieldLayout) -> None:
+        """Adds targets on the field which your vision system is designed to detect. The {@link
+        PhotonCamera}s simulated from this system will report the location of the camera relative to
+        the subset of these targets which are visible from the given camera position.
+
+        The AprilTags from this layout will be added as vision targets under the type "apriltag".
+        The poses added preserve the tag layout's current alliance origin. If the tag layout's alliance
+        origin is changed, these added tags will have to be cleared and re-added.
+
+        :param tagLayout: The field tag layout to get Apriltag poses and IDs from
+        """
         targets: list[VisionTargetSim] = []
         for tag in layout.getTags():
             tag_pose = layout.getTagPose(tag.ID)
@@ -172,9 +243,15 @@ class VisionSystemSim:
     def getRobotPose(
         self, timestamp: seconds = wpilib.Timer.getFPGATimestamp()
     ) -> Pose3d | None:
+        """Get the robot pose in meters saved by the vision system at this timestamp.
+
+        :param timestamp: Timestamp of the desired robot pose
+        """
+
         return self.robotPoseBuffer.sample(timestamp)
 
     def resetRobotPose(self, robotPose: Pose2d | Pose3d) -> None:
+        """Clears all previous robot poses and sets robotPose at current time."""
         if type(robotPose) is Pose2d:
             robotPose = Pose3d(robotPose)
         assert type(robotPose) is Pose3d
@@ -186,16 +263,23 @@ class VisionSystemSim:
         return self.dbgField
 
     def update(self, robotPose: Pose2d | Pose3d) -> None:
+        """Periodic update. Ensure this is called repeatedly-- camera performance is used to automatically
+        determine if a new frame should be submitted.
+
+        :param robotPoseMeters: The simulated robot pose in meters
+        """
         if type(robotPose) is Pose2d:
             robotPose = Pose3d(robotPose)
         assert type(robotPose) is Pose3d
 
+        # update vision targets on field
         for targetType, targets in self.targetSets.items():
             posesToAdd: list[Pose2d] = []
             for target in targets:
                 posesToAdd.append(target.getPose().toPose2d())
             self.dbgField.getObject(targetType).setPoses(posesToAdd)
 
+        # save "real" robot poses over time
         now = wpilib.Timer.getFPGATimestamp()
         self.robotPoseBuffer.addSample(now, robotPose)
         self.dbgField.setRobotPose(robotPose.toPose2d())
@@ -208,17 +292,22 @@ class VisionSystemSim:
         visTgtPoses2d: list[Pose2d] = []
         cameraPoses2d: list[Pose2d] = []
         processed = False
+        # process each camera
         for camSim in self.camSimMap.values():
+            # check if this camera is ready to process and get latency
             optTimestamp = camSim.consumeNextEntryTime()
             if optTimestamp is None:
                 continue
             else:
                 processed = True
 
+            # when this result "was" read by NT
             timestampNt = optTimestamp
             latency = camSim.prop.estLatency()
+            # the image capture timestamp in seconds of this result
             timestampCapture = timestampNt * 1.0e-6 - latency
 
+            # use camera pose from the image capture timestamp
             lateRobotPose = self.getRobotPose(timestampCapture)
             robotToCamera = self.getRobotToCamera(camSim, timestampCapture)
             if lateRobotPose is None or robotToCamera is None:
@@ -226,8 +315,11 @@ class VisionSystemSim:
             lateCameraPose = lateRobotPose + robotToCamera
             cameraPoses2d.append(lateCameraPose.toPose2d())
 
+            # process a PhotonPipelineResult with visible targets
             camResult = camSim.process(latency, lateCameraPose, allTargets)
+            # publish this info to NT at estimated timestamp of receive
             camSim.submitProcessedFrame(camResult, timestampNt)
+            # display debug results
             for tgt in camResult.getTargets():
                 trf = tgt.getBestCameraToTarget()
                 if trf == Transform3d():

photonlibpy/simulation/visionTargetSim.py

@@ -6,7 +6,16 @@ from ..estimation.targetModel import TargetModel
 
 
 class VisionTargetSim:
+    """Describes a vision target located somewhere on the field that your vision system can detect."""
+
     def __init__(self, pose: Pose3d, model: TargetModel, id: int = -1):
+        """Describes a fiducial tag located somewhere on the field that your vision system can detect.
+
+        :param pose:  Pose3d of the tag in field-relative coordinates
+        :param model: TargetModel which describes the shape of the target(tag)
+        :param id:    The ID of this fiducial tag
+        """
+
         self.pose: Pose3d = pose
         self.model: TargetModel = model
         self.fiducialId: int = id
@@ -47,4 +56,5 @@ class VisionTargetSim:
         return self.model
 
     def getFieldVertices(self) -> list[Translation3d]:
+        """This target's vertices offset from its field pose."""
         return self.model.getFieldVertices(self.pose)

photonlibpy/version.py

@@ -1,2 +1,2 @@
-PHOTONLIB_VERSION="v2025.0.0.beta.3"
-PHOTONVISION_VERSION="v2025.0.0-beta-3"
+PHOTONLIB_VERSION="v2025.0.0.beta.4"
+PHOTONVISION_VERSION="v2025.0.0-beta-4"

{photonlibpy-2025.0.0b3.dist-info → photonlibpy-2025.0.0b4.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: photonlibpy
-Version: 2025.0.0b3
-Summary: Pure-python implementation of PhotonLib for interfacing with PhotonVision on coprocessors. Implemented with PhotonVision version v2025.0.0-beta-3 .
+Version: 2025.0.0b4
+Summary: Pure-python implementation of PhotonLib for interfacing with PhotonVision on coprocessors. Implemented with PhotonVision version v2025.0.0-beta-4 .
 Home-page: https://photonvision.org
 Author: Photonvision Development Team
 Description-Content-Type: text/markdown
@@ -12,6 +12,5 @@ Requires-Dist: robotpy-apriltag<2026,>=2025.0.0b1
 Requires-Dist: robotpy-cscore<2026,>=2025.0.0b1
 Requires-Dist: pyntcore<2026,>=2025.0.0b1
 Requires-Dist: opencv-python; platform_machine != "roborio"
-Requires-Dist: robotpy-opencv; platform_machine == "roborio"
 
 A Pure-python implementation of PhotonLib

{photonlibpy-2025.0.0b3.dist-info → photonlibpy-2025.0.0b4.dist-info}/RECORD

@@ -1,15 +1,15 @@
 photonlibpy/__init__.py,sha256=WW1OGrrcNXwwxaHSZlkxmhH2GYiQIHHxSxGVTJZhZbY,1136
 photonlibpy/estimatedRobotPose.py,sha256=X7wF9xdPXGKSVy0MY0qrWZJOEbuZPd721lYp0KXKlP0,1603
 photonlibpy/packet.py,sha256=5YomViVFwOljL2FGOetWM9FbPc_yCQ15ylzkYlgLIs8,9724
-photonlibpy/photonCamera.py,sha256=061meWm5G36_9vByAUBFCor0fR4G24baw306xt_cWB8,10181
+photonlibpy/photonCamera.py,sha256=80-UKakvcgJ79vw80e2yUqZZfoQtpC1_lopnXpfgvOY,12823
 photonlibpy/photonPoseEstimator.py,sha256=2iMqxPFsQHTsq95yv-WCSv1a6wXNcHPqOyMc4Bu6IG0,12584
-photonlibpy/version.py,sha256=A48GfU-qwEM5vulc7mQd7EH8j_mm-7dL2tuMzcswSqg,77
+photonlibpy/version.py,sha256=Ew1xD5CpZetX_p3ReR01MPCVsroMfk2ZpgH42q0Fubg,77
 photonlibpy/estimation/__init__.py,sha256=pZ-d6fN1DJvT-lRl4FfIos5HAvlzmetIOrGIinrdv7k,223
 photonlibpy/estimation/cameraTargetRelation.py,sha256=i7DPBXtkZve4ToXQscEIe-5F1oGQ1Qmf5QBaE__EeMQ,1158
-photonlibpy/estimation/openCVHelp.py,sha256=6ynO0WbccVxbUCeDu4QgISgipqiqs-erLd14rnSSH-c,6726
-photonlibpy/estimation/rotTrlTransform3d.py,sha256=_5q3oMdbYRVBhzxQt5UwyRE7AXkhT3Fth5Ljrj3gANY,1728
-photonlibpy/estimation/targetModel.py,sha256=ZfuiB0ZDNM8gMum5nuq6KWyEeFts49jYgMo7-oojjY0,3726
-photonlibpy/estimation/visionEstimation.py,sha256=v4WkVtEQd5Q9OWxrcJAseIjP-trMHj_MDzMj4fcfjtw,3019
+photonlibpy/estimation/openCVHelp.py,sha256=h36tOunGaDfs1yp1kAyK-BX0DqdNXZSN8T8ms-ReQas,12277
+photonlibpy/estimation/rotTrlTransform3d.py,sha256=oRYk4V1XF7guNxefJsCPcBWPIkKZl0HYD_Gs86wwToE,2671
+photonlibpy/estimation/targetModel.py,sha256=fIhkf0-_Sfv-KhYEBnhFWMF4Xu84FfF6B-KUEsuuGjQ,6459
+photonlibpy/estimation/visionEstimation.py,sha256=Q4KWdLCV1H0wJUJCzG7OYNhVmk2jR1iPUmX_PFylLdA,4174
 photonlibpy/generated/MultiTargetPNPResultSerde.py,sha256=CzsCosHUnzxAoSC_sSAqpsXsDp54KW-BClnIXdzfMPc,2506
 photonlibpy/generated/PhotonPipelineMetadataSerde.py,sha256=9pq5XUEDEoRowCd7sRnuGV7xtugu5HZCRrnwqZG2xXc,2887
 photonlibpy/generated/PhotonPipelineResultSerde.py,sha256=jTf1obU2jPNDsxvt-tl9Ty_qzJws9Wqron3C1QiHkP8,3137
@@ -17,20 +17,20 @@ photonlibpy/generated/PhotonTrackedTargetSerde.py,sha256=-6vKir_ABDVBGbg8ktM48IK
 photonlibpy/generated/PnpResultSerde.py,sha256=YoTKdQ51oSdxC-7Poy6hunL0-zkMKvP5uedqaHWPudY,2693
 photonlibpy/generated/TargetCornerSerde.py,sha256=kziD_rQIwyhzPfgOaDgn-3d87tvtXiAYbBjzu76biYU,2190
 photonlibpy/generated/__init__.py,sha256=mElM8M88---wxTWO-SRqIJ4EfxN0fdIUwZBZ-UIGuRw,428
-photonlibpy/networktables/NTTopicSet.py,sha256=NduTI3c3fG4MuVcY2cuLIoV1i1PSxxYzqBOt24ngS9k,2708
+photonlibpy/networktables/NTTopicSet.py,sha256=TXJyVg6S8gONeuRqX_NI0FdxYw51bNLlFIAQ4Y2wyVg,3104
 photonlibpy/networktables/__init__.py,sha256=o_LxTdyIylAszMy_zhUtTkXHyu6jqxccccj78d44OrI,35
 photonlibpy/simulation/__init__.py,sha256=HKJV02of5d8bOnuI7syLzSYtOYge7XUrHSaLvawh99M,227
-photonlibpy/simulation/photonCameraSim.py,sha256=BJ870459FdaO1HLkAMfA23W2S8S9axn3rZUPyxQfH40,14078
-photonlibpy/simulation/simCameraProperties.py,sha256=gcRfMOH5zQhv8mBElSo8GT7yOC9dA0EsQoJz-1WsCCw,19960
+photonlibpy/simulation/photonCameraSim.py,sha256=5GTPdU7SRAahhtXYHcbm0GJEzARWA7lyBG3v279pqGk,19891
+photonlibpy/simulation/simCameraProperties.py,sha256=bJ6Xvos2glO0-R_a0Wv4eKESnQD13GSYqhwPQdVr1eQ,27082
 photonlibpy/simulation/videoSimUtil.py,sha256=xMuTvJ2Jx9IoQqmAJi_zUm06MdEwhVpIz9OyzYQp0k4,29
-photonlibpy/simulation/visionSystemSim.py,sha256=WZKYdu89IVchcCsXR04AXVQv78F_KgZIQRZ00ocusWE,8814
-photonlibpy/simulation/visionTargetSim.py,sha256=AN7jXW3guQfNUu2EiQl23Jj8Mkgn4gYmRphGXL0-Dqk,1734
+photonlibpy/simulation/visionSystemSim.py,sha256=ln1TYVMXUreg6nxrVZJ7lw8puvgLbBBde_ciM2CH5G4,13788
+photonlibpy/simulation/visionTargetSim.py,sha256=FH85fKE4NntowUvssfgZ1KlE-I_3Z-QuAgb2bFqvfdY,2219
 photonlibpy/targeting/TargetCorner.py,sha256=ouKj3E5uD76OZSNHHuSDzKOY65a8HqtcOsuejH-MVsU,276
 photonlibpy/targeting/__init__.py,sha256=YzINSpq6A0cjr-yAQcFqHoiYdLGKPFXThlVYlMjY11w,295
 photonlibpy/targeting/multiTargetPNPResult.py,sha256=Y9rweHtMzoCZ6mv6F8CutQi2Thq5pHN0ydBWvTCsOwY,806
 photonlibpy/targeting/photonPipelineResult.py,sha256=MbaSyHZTJpoKTtLOZztpSGSt9xWWFqhzgwj8medObVA,2732
 photonlibpy/targeting/photonTrackedTarget.py,sha256=zCoFp32hX-3GmBYEmsYBQieBoMzXtP2F_55_q0zPOXA,1956
-photonlibpy-2025.0.0b3.dist-info/METADATA,sha256=C6jySUa1aCRwXFf3ZKZS8l8C_MV4pnnfBS6Ueho98WM,750
-photonlibpy-2025.0.0b3.dist-info/WHEEL,sha256=bFJAMchF8aTQGUgMZzHJyDDMPTO3ToJ7x23SLJa1SVo,92
-photonlibpy-2025.0.0b3.dist-info/top_level.txt,sha256=T8Xc6U6he2VjKUAca6zawSkHdUZuLanxYIc4nxw2ctc,12
-photonlibpy-2025.0.0b3.dist-info/RECORD,,
+photonlibpy-2025.0.0b4.dist-info/METADATA,sha256=zybpLt0J7EMylub2yKyAugXJ-lt7-uwrAhFV7KGv51U,689
+photonlibpy-2025.0.0b4.dist-info/WHEEL,sha256=bFJAMchF8aTQGUgMZzHJyDDMPTO3ToJ7x23SLJa1SVo,92
+photonlibpy-2025.0.0b4.dist-info/top_level.txt,sha256=T8Xc6U6he2VjKUAca6zawSkHdUZuLanxYIc4nxw2ctc,12
+photonlibpy-2025.0.0b4.dist-info/RECORD,,