Team2890/PhotonVision
4
0
Fork 0
mirror of https://github.com/PhotonVision/photonvision synced 2026-06-20 00:51:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix javadoc warnings (#2266)

Browse Source 
Persuant to #1093, I added as many docstrings as I could, at least for
things I knew about. Some of the classes I just suppressed the Javadoc
warnings in because they aren't particularly useful to document. This
gets us down to less than 100 Javadoc warnings in total. Docs for core
classes on the C++ side were also added for parity.
This commit is contained in:
Gold856
2026-01-11 14:25:49 -05:00
committed by GitHub
parent a5dc9ec0d6
commit e4749a3ea9
39 changed files with 1306 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
photon-lib/src/main/java/org/photonvision/simulation/PhotonCameraSim.java
View File

@@ -69,7 +69,9 @@ import org.photonvision.targeting.PnpResult;
public class PhotonCameraSim implements AutoCloseable {
private final PhotonCamera cam;
@SuppressWarnings("doclint")
protected NTTopicSet ts = new NTTopicSet();
private long heartbeatCounter = 1;
/** This simulated camera's {@link SimCameraProperties} */
@@ -168,7 +170,7 @@ public class PhotonCameraSim implements AutoCloseable {
*
* @param camera The camera to be simulated
* @param prop Properties of this camera such as FOV and FPS
* @param minTargetAreaPercent The minimum percentage(0 - 100) a detected target must take up of
* @param minTargetAreaPercent The minimum percentage (0 - 100) a detected target must take up of
* the camera's image to be processed. Match this with your contour filtering settings in the
* PhotonVision GUI.
* @param maxSightRangeMeters Maximum distance at which the target is illuminated to your camera.
@@ -190,7 +192,7 @@ public class PhotonCameraSim implements AutoCloseable {
*
* @param camera The camera to be simulated
* @param prop Properties of this camera such as FOV and FPS
* @param minTargetAreaPercent The minimum percentage(0 - 100) a detected target must take up of
* @param minTargetAreaPercent The minimum percentage (0 - 100) a detected target must take up of
* the camera's image to be processed. Match this with your contour filtering settings in the
* PhotonVision GUI.
* @param maxSightRangeMeters Maximum distance at which the target is illuminated to your camera.
@@ -208,22 +210,50 @@ public class PhotonCameraSim implements AutoCloseable {
this.maxSightRangeMeters = maxSightRangeMeters;
}
/**
* Returns the camera being simulated.
*
* @return The camera
*/
public PhotonCamera getCamera() {
return cam;
}
/**
* Returns the minimum percentage (0 - 100) a detected target must take up of the camera's image
* to be processed.
*
* @return The percentage
*/
public double getMinTargetAreaPercent() {
return minTargetAreaPercent;
}
/**
* Returns the minimum number of pixels a detected target must take up in the camera's image to be
* processed.
*
* @return The number of pixels
*/
public double getMinTargetAreaPixels() {
return minTargetAreaPercent / 100.0 * prop.getResArea();
}
/**
* Returns the maximum distance at which the target is illuminated to your camera. Note that
* minimum target area of the image is separate from this.
*
* @return The distance in meters
*/
public double getMaxSightRangeMeters() {
return maxSightRangeMeters;
}
/**
* Returns the order the targets are sorted in the pipeline result.
*
* @return The target sorting order
*/
public PhotonTargetSortMode getTargetSortMode() {
return sortMode;
}
@@ -261,6 +291,7 @@ public class PhotonCameraSim implements AutoCloseable {
* Determines if all target points are inside the camera's image.
*
* @param points The target's 2d image points
* @return True if all the target points are inside the camera's image, false otherwise.
*/
public boolean canSeeCorners(Point[] points) {
for (var point : points) {
@@ -306,30 +337,40 @@ public class PhotonCameraSim implements AutoCloseable {
}
/**
* The minimum percentage(0 - 100) a detected target must take up of the camera's image to be
* processed.
* Sets the minimum percentage (0 - 100) a detected target must take up of the camera's image to
* be processed.
*
* @param areaPercent The percentage
*/
public void setMinTargetAreaPercent(double areaPercent) {
this.minTargetAreaPercent = areaPercent;
}
/**
* The minimum number of pixels a detected target must take up in the camera's image to be
* Sets the minimum number of pixels a detected target must take up in the camera's image to be
* processed.
*
* @param areaPx The number of pixels
*/
public void setMinTargetAreaPixels(double areaPx) {
this.minTargetAreaPercent = areaPx / prop.getResArea() * 100;
}
/**
* Maximum distance at which the target is illuminated to your camera. Note that minimum target
* area of the image is separate from this.
* Sets the maximum distance at which the target is illuminated to your camera. Note that minimum
* target area of the image is separate from this.
*
* @param rangeMeters The distance in meters
*/
public void setMaxSightRange(double rangeMeters) {
this.maxSightRangeMeters = rangeMeters;
}
/** Defines the order the targets are sorted in the pipeline result. */
/**
* Defines the order the targets are sorted in the pipeline result.
*
* @param sortMode The target sorting order
*/
public void setTargetSortMode(PhotonTargetSortMode sortMode) {
if (sortMode != null) this.sortMode = sortMode;
}
@@ -338,6 +379,8 @@ public class PhotonCameraSim implements AutoCloseable {
* Sets whether the raw video stream simulation is enabled.
*
* <p>Note: This may increase loop times.
*
* @param enabled Whether or not to enable the raw video stream
*/
public void enableRawStream(boolean enabled) {
videoSimRawEnabled = enabled;
@@ -347,6 +390,8 @@ public class PhotonCameraSim implements AutoCloseable {
* Sets whether a wireframe of the field is drawn to the raw video stream.
*
* <p>Note: This will dramatically increase loop times.
*
* @param enabled Whether or not to enable the wireframe in the raw video stream
*/
public void enableDrawWireframe(boolean enabled) {
videoSimWireframeEnabled = enabled;
@@ -363,7 +408,11 @@ public class PhotonCameraSim implements AutoCloseable {
videoSimWireframeResolution = resolution;
}
/** Sets whether the processed video stream simulation is enabled. */
/**
* Sets whether the processed video stream simulation is enabled.
*
* @param enabled Whether or not to enable the processed video stream
*/
public void enableProcessedStream(boolean enabled) {
videoSimProcEnabled = enabled;
}

152
photon-lib/src/main/java/org/photonvision/simulation/SimCameraProperties.java
View File

@@ -89,7 +89,7 @@ public class SimCameraProperties {
}
/**
* Reads camera properties from a photonvision <code>config.json</code> file. This is only the
* Reads camera properties from a PhotonVision <code>config.json</code> file. This is only the
* resolution, camera intrinsics, distortion coefficients, and average/std. dev. pixel error.
* Other camera properties must be set.
*
@@ -104,7 +104,7 @@ public class SimCameraProperties {
}
/**
* Reads camera properties from a photonvision <code>config.json</code> file. This is only the
* Reads camera properties from a PhotonVision <code>config.json</code> file. This is only the
* resolution, camera intrinsics, distortion coefficients, and average/std. dev. pixel error.
* Other camera properties must be set.
*
@@ -232,8 +232,11 @@ public class SimCameraProperties {
}
/**
* Sets the simulated FPS for this camera.
*
* @param fps The average frames per second the camera should process at. <b>Exposure time limits
* FPS if set!</b>
* @return This camera properties object for use in chaining
*/
public SimCameraProperties setFPS(double fps) {
frameSpeedMs = Math.max(1000.0 / fps, exposureTimeMs);
@@ -242,8 +245,11 @@ public class SimCameraProperties {
}
/**
* Sets the simulated exposure time for this camera.
*
* @param exposureTimeMs The amount of time the "shutter" is open for one frame. Affects motion
* blur. <b>Frame speed(from FPS) is limited to this!</b>
* @return This camera properties object for use in chaining
*/
public SimCameraProperties setExposureTimeMs(double exposureTimeMs) {
this.exposureTimeMs = exposureTimeMs;
@@ -253,8 +259,11 @@ public class SimCameraProperties {
}
/**
* Sets the simulated latency for this camera.
*
* @param avgLatencyMs The average latency (from image capture to data published) in milliseconds
* a frame should have
* @return This camera properties object for use in chaining
*/
public SimCameraProperties setAvgLatencyMs(double avgLatencyMs) {
this.avgLatencyMs = avgLatencyMs;
@@ -263,7 +272,10 @@ public class SimCameraProperties {
}
/**
* Sets the simulated latency variation for this camera.
*
* @param latencyStdDevMs The standard deviation in milliseconds of the latency
* @return This camera properties object for use in chaining
*/
public SimCameraProperties setLatencyStdDevMs(double latencyStdDevMs) {
this.latencyStdDevMs = latencyStdDevMs;
@@ -271,14 +283,29 @@ public class SimCameraProperties {
return this;
}
/**
* Gets the width of the simulated camera image.
*
* @return The width in pixels
*/
public int getResWidth() {
return resWidth;
}
/**
* Gets the height of the simulated camera image.
*
* @return The height in pixels
*/
public int getResHeight() {
return resHeight;
}
/**
* Gets the area of the simulated camera image.
*
* @return The area in pixels
*/
public int getResArea() {
return resWidth * resHeight;
}
@@ -292,30 +319,66 @@ public class SimCameraProperties {
return camIntrinsics.copy();
}
/**
* Returns the camera calibration's distortion coefficients, in OPENCV8 form. Higher-order terms
* are set to 0
*
* @return The distortion coefficients in an 8d vector
*/
public Vector<N8> getDistCoeffs() {
return new Vector<>(distCoeffs);
}
/**
* Gets the FPS of the simulated camera.
*
* @return The FPS
*/
public double getFPS() {
return 1000.0 / frameSpeedMs;
}
/**
* Gets the time per frame of the simulated camera.
*
* @return The time per frame in milliseconds
*/
public double getFrameSpeedMs() {
return frameSpeedMs;
}
/**
* Gets the exposure time of the simulated camera.
*
* @return The exposure time in milliseconds
*/
public double getExposureTimeMs() {
return exposureTimeMs;
}
/**
* Gets the average latency of the simulated camera.
*
* @return The average latency in milliseconds
*/
public double getAvgLatencyMs() {
return avgLatencyMs;
}
/**
* Gets the time per frame of the simulated camera.
*
* @return The time per frame in milliseconds
*/
public double getLatencyStdDevMs() {
return latencyStdDevMs;
}
/**
* Returns a copy of the camera properties.
*
* @return The copied camera properties
*/
public SimCameraProperties copy() {
var newProp = new SimCameraProperties();
newProp.setCalibration(resWidth, resHeight, camIntrinsics, distCoeffs);
@@ -328,10 +391,11 @@ public class SimCameraProperties {
}
/**
* The percentage(0 - 100) of this camera's resolution the contour takes up in pixels of the
* The percentage (0 - 100) of this camera's resolution the contour takes up in pixels of the
* image.
*
* @param points Points of the contour
* @return The percentage
*/
public double getContourAreaPercent(Point[] points) {
return Imgproc.contourArea(new MatOfPoint2f(OpenCVHelp.getConvexHull(points)))
@@ -567,7 +631,12 @@ public class SimCameraProperties {
else return new Pair<>(null, null);
}
/** Returns these points after applying this camera's estimated noise. */
/**
* Returns these points after applying this camera's estimated noise.
*
* @param points The points to add noise to
* @return The points with noise
*/
public Point[] estPixelNoise(Point[] points) {
if (avgErrorPx == 0 && errorStdDevPx == 0) return points;
@@ -584,14 +653,18 @@ public class SimCameraProperties {
}
/**
* @return Noisy estimation of a frame's processing latency in milliseconds
* Returns an estimation of a frame's processing latency with noise added.
*
* @return The latency estimate in milliseconds
*/
public double estLatencyMs() {
return Math.max(avgLatencyMs + rand.nextGaussian() * latencyStdDevMs, 0);
}
/**
* @return Estimate how long until the next frame should be processed in milliseconds
* Estimates how long until the next frame should be processed.
*
* @return The estimated time until the next frame in milliseconds
*/
public double estMsUntilNextFrame() {
// exceptional processing latency blocks the next frame
@@ -600,11 +673,28 @@ public class SimCameraProperties {
// pre-calibrated example cameras
/** 960x720 resolution, 90 degree FOV, "perfect" lagless camera */
/**
* Creates a set of camera properties where the camera has a 960x720 resolution, 90 degree FOV,
* and is a "perfect" lagless camera.
*
* @return The properties for this theoretical camera
*/
public static SimCameraProperties PERFECT_90DEG() {
return new SimCameraProperties();
}
/**
* Creates a set of camera properties matching those of Microsoft Lifecam running on a Raspberry
* Pi 4 at 320x240 resolution.
*
* <p>Note that this set of properties represents <i>a camera setup</i>, not <i>your camera
* setup</i>. Do not use these camera properties for any non-sim vision calculations, especially
* the calibration data. Always use your camera's calibration data to do vision calculations in
* non-sim environments. These properties exist as a sample that may be used to get representative
* data in sim.
*
* @return The properties for this camera setup
*/
public static SimCameraProperties PI4_LIFECAM_320_240() {
var prop = new SimCameraProperties();
prop.setCalibration(
@@ -639,6 +729,18 @@ public class SimCameraProperties {
return prop;
}
/**
* Creates a set of camera properties matching those of Microsoft Lifecam running on a Raspberry
* Pi 4 at 640x480 resolution.
*
* <p>Note that this set of properties represents <i>a camera setup</i>, not <i>your camera
* setup</i>. Do not use these camera properties for any non-sim vision calculations, especially
* the calibration data. Always use your camera's calibration data to do vision calculations in
* non-sim environments. These properties exist as a sample that may be used to get representative
* data in sim.
*
* @return The properties for this camera setup
*/
public static SimCameraProperties PI4_LIFECAM_640_480() {
var prop = new SimCameraProperties();
prop.setCalibration(
@@ -673,6 +775,18 @@ public class SimCameraProperties {
return prop;
}
/**
* Creates a set of camera properties matching those of a Limelight 2 running at 640x480
* resolution.
*
* <p>Note that this set of properties represents <i>a camera setup</i>, not <i>your camera
* setup</i>. Do not use these camera properties for any non-sim vision calculations, especially
* the calibration data. Always use your camera's calibration data to do vision calculations in
* non-sim environments. These properties exist as a sample that may be used to get representative
* data in sim.
*
* @return The properties for this camera setup
*/
public static SimCameraProperties LL2_640_480() {
var prop = new SimCameraProperties();
prop.setCalibration(
@@ -706,6 +820,18 @@ public class SimCameraProperties {
return prop;
}
/**
* Creates a set of camera properties matching those of a Limelight 2 running at 960x720
* resolution.
*
* <p>Note that this set of properties represents <i>a camera setup</i>, not <i>your camera
* setup</i>. Do not use these camera properties for any non-sim vision calculations, especially
* the calibration data. Always use your camera's calibration data to do vision calculations in
* non-sim environments. These properties exist as a sample that may be used to get representative
* data in sim.
*
* @return The properties for this camera setup
*/
public static SimCameraProperties LL2_960_720() {
var prop = new SimCameraProperties();
prop.setCalibration(
@@ -740,6 +866,18 @@ public class SimCameraProperties {
return prop;
}
/**
* Creates a set of camera properties matching those of a Limelight 2 running at 1280x720
* resolution.
*
* <p>Note that this set of properties represents <i>a camera setup</i>, not <i>your camera
* setup</i>. Do not use these camera properties for any non-sim vision calculations, especially
* the calibration data. Always use your camera's calibration data to do vision calculations in
* non-sim environments. These properties exist as a sample that may be used to get representative
* data in sim.
*
* @return The properties for this camera setup
*/
public static SimCameraProperties LL2_1280_720() {
var prop = new SimCameraProperties();
prop.setCalibration(

18
photon-lib/src/main/java/org/photonvision/simulation/VideoSimUtil.java
View File

@@ -73,6 +73,8 @@ public class VideoSimUtil {
kTag36h11MarkerPts = get36h11MarkerPts();
}
private VideoSimUtil() {}
/** Updates the properties of this CvSource video stream with the given camera properties. */
public static void updateVideoProp(CvSource video, SimCameraProperties prop) {
video.setResolution(prop.getResWidth(), prop.getResHeight());
@@ -87,6 +89,7 @@ public class VideoSimUtil {
* <p>Order of corners returned is: [BL, BR, TR, TL]
*
* @param size Size of image
* @return The corners
*/
public static Point[] getImageCorners(Size size) {
return new Point[] {
@@ -116,7 +119,11 @@ public class VideoSimUtil {
frame.getHeight(), frame.getWidth(), CvType.CV_8UC1, frame.getData(), frame.getStride());
}
/** Gets the points representing the marker(black square) corners. */
/**
* Gets the points representing the marker(black square) corners.
*
* @return The points
*/
public static Point[] get36h11MarkerPts() {
return get36h11MarkerPts(1);
}
@@ -125,6 +132,7 @@ public class VideoSimUtil {
* Gets the points representing the marker(black square) corners.
*
* @param scale The scale of the tag image (10*scale x 10*scale image)
* @return The points
*/
public static Point[] get36h11MarkerPts(int scale) {
var roi36h11 = new Rect(new Point(1, 1), new Size(8, 8));
@@ -276,12 +284,12 @@ public class VideoSimUtil {
* resolution.
*
* @param thickness480p A hypothetical line thickness in a 640x480 image
* @param destinationImg The destination image to scale to
* @param destination The destination image to scale to
* @return Scaled thickness which cannot be less than 1
*/
public static double getScaledThickness(double thickness480p, Mat destinationImg) {
double scaleX = destinationImg.width() / 640.0;
double scaleY = destinationImg.height() / 480.0;
public static double getScaledThickness(double thickness480p, Mat destination) {
double scaleX = destination.width() / 640.0;
double scaleY = destination.height() / 480.0;
double minScale = Math.min(scaleX, scaleY);
return Math.max(thickness480p * minScale, 1.0);
}

47
photon-lib/src/main/java/org/photonvision/simulation/VisionSystemSim.java
View File

@@ -119,6 +119,7 @@ public class VisionSystemSim {
/**
* Remove a simulated camera from this vision system.
*
* @param cameraSim The camera to remove
* @return If the camera was present and removed
*/
public boolean removeCamera(PhotonCameraSim cameraSim) {
@@ -202,6 +203,7 @@ public class VisionSystemSim {
/**
* Reset the transform history for this camera to just the current transform.
*
* @param cameraSim The camera to reset
* @return If the cameraSim was valid and transforms were reset
*/
public boolean resetCameraTransforms(PhotonCameraSim cameraSim) {
@@ -214,6 +216,11 @@ public class VisionSystemSim {
return true;
}
/**
* Returns all the vision targets on the field.
*
* @return The vision targets
*/
public Set<VisionTargetSim> getVisionTargets() {
var all = new HashSet<VisionTargetSim>();
for (var entry : targetSets.entrySet()) {
@@ -222,6 +229,12 @@ public class VisionSystemSim {
return all;
}
/**
* Returns all the vision targets of the specified type on the field.
*
* @param type The type of vision targets to return
* @return The vision targets
*/
public Set<VisionTargetSim> getVisionTargets(String type) {
return targetSets.get(type);
}
@@ -276,18 +289,33 @@ public class VisionSystemSim {
}
}
/** Removes every {@link VisionTargetSim} from the simulated field. */
public void clearVisionTargets() {
targetSets.clear();
}
/** Removes all simulated AprilTag targets from the simulated field. */
public void clearAprilTags() {
removeVisionTargets("apriltag");
}
/**
* Removes every {@link VisionTargetSim} of the specified type from the simulated field.
*
* @param type Type of target (e.g. "cargo"). Same as the type passed into {@link
* #addVisionTargets(String, VisionTargetSim...)}
* @return The removed targets, or null if no targets of the specified type exist
*/
public Set<VisionTargetSim> removeVisionTargets(String type) {
return targetSets.remove(type);
}
/**
* Removes the specified {@link VisionTargetSim}s from the simulated field.
*
* @param targets The targets to remove
* @return The targets that were actually removed
*/
public Set<VisionTargetSim> removeVisionTargets(VisionTargetSim... targets) {
var removeList = List.of(targets);
var removedSet = new HashSet<VisionTargetSim>();
@@ -305,7 +333,11 @@ public class VisionSystemSim {
return removedSet;
}
/** Get the latest robot pose in meters saved by the vision system. */
/**
* Get the latest robot pose in meters saved by the vision system.
*
* @return The latest robot pose
*/
public Pose3d getRobotPose() {
return getRobotPose(Timer.getFPGATimestamp());
}
@@ -314,17 +346,26 @@ public class VisionSystemSim {
* Get the robot pose in meters saved by the vision system at this timestamp.
*
* @param timestamp Timestamp of the desired robot pose
* @return The robot pose
*/
public Pose3d getRobotPose(double timestamp) {
return robotPoseBuffer.getSample(timestamp).orElse(new Pose3d());
}
/** Clears all previous robot poses and sets robotPose at current time. */
/**
* Clears all previous robot poses and sets robotPose at current time.
*
* @param robotPose The robot pose
*/
public void resetRobotPose(Pose2d robotPose) {
resetRobotPose(new Pose3d(robotPose));
}
/** Clears all previous robot poses and sets robotPose at current time. */
/**
* Clears all previous robot poses and sets robotPose at current time.
*
* @param robotPose The robot pose
*/
public void resetRobotPose(Pose3d robotPose) {
robotPoseBuffer.clear();
robotPoseBuffer.addSample(Timer.getFPGATimestamp(), robotPose);

24
photon-lib/src/main/java/org/photonvision/simulation/VisionTargetSim.java
View File

@@ -40,7 +40,7 @@ public class VisionTargetSim {
* Describes a vision target 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
* @param model TargetModel which describes the geometry of the target
*/
public VisionTargetSim(Pose3d pose, TargetModel model) {
this.pose = pose;
@@ -52,7 +52,7 @@ public class VisionTargetSim {
* 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 model TargetModel which describes the geometry of the target(tag)
* @param id The ID of this fiducial tag
*/
public VisionTargetSim(Pose3d pose, TargetModel model, int id) {
@@ -61,18 +61,38 @@ public class VisionTargetSim {
this.fiducialID = id;
}
/**
* Sets the pose of this target on the field.
*
* @param pose The pose in field-relative coordinates
*/
public void setPose(Pose3d pose) {
this.pose = pose;
}
/**
* Sets the model describing this target's geometry.
*
* @param model The model of the target
*/
public void setModel(TargetModel model) {
this.model = model;
}
/**
* Returns the pose of this target on the field.
*
* @return The pose in field-relative coordinates
*/
public Pose3d getPose() {
return pose;
}
/**
* Returns the model describing this target's geometry.
*
* @return The model of the target
*/
public TargetModel getModel() {
return model;
}