From 0f9b191ccbd67cb5567cbb370e5b68d872b96120 Mon Sep 17 00:00:00 2001 From: Fan-Wu Yang Date: Mon, 7 Aug 2017 16:13:15 +1200 Subject: [PATCH] Added doc strings to RaceXML Creator #story[1096] --- .../main/java/mock/xml/RaceXMLCreator.java | 68 ++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/racevisionGame/src/main/java/mock/xml/RaceXMLCreator.java b/racevisionGame/src/main/java/mock/xml/RaceXMLCreator.java index 8e13b842..e876ffb9 100644 --- a/racevisionGame/src/main/java/mock/xml/RaceXMLCreator.java +++ b/racevisionGame/src/main/java/mock/xml/RaceXMLCreator.java @@ -15,10 +15,17 @@ import javax.xml.bind.Marshaller; import java.io.StringWriter; /** - * Created by Gondr on 3/08/2017. + * Helper Class for creating a Race XML */ public class RaceXMLCreator { + /** + * Copy the race to a mock.xml.Race class from a RaceXMlReader + * @param reader RaceXMlReader + * @return string of the new mock.xml.Race + * @throws InvalidRaceDataException If the reader is unable to be read + * @throws XMLReaderException If the reader is unable to be read + */ public static Race copyRace(RaceXMLReader reader) throws InvalidRaceDataException, XMLReaderException { RaceFactory raceFactory = new RaceFactory(); Race race = raceFactory.createRace(); @@ -80,6 +87,12 @@ public class RaceXMLCreator { return race; } + /** + * Sets a mock.xml.Mark from a shared.model.Mark + * @param raceFactory race Factory for creating mock.xml.Race classes and subclasses + * @param mark Mark to be converted. + * @return converted mock.xml.Mark. + */ public static Race.Course.CompoundMark.Mark setMarkFromMark(RaceFactory raceFactory, Mark mark){ if (mark != null) { Race.Course.CompoundMark.Mark m = raceFactory.createRaceCourseCompoundMarkMark(); @@ -92,6 +105,11 @@ public class RaceXMLCreator { return null; } + /** + * get the windward gate in a race + * @param reader reads in the mark + * @return the windward gate. + */ public static CompoundMark getWindwardGate(RaceXMLReader reader){ for (CompoundMark mark: reader.getCompoundMarks()){ if (mark.getName().equals("Windward Gate")) return mark; @@ -99,6 +117,11 @@ public class RaceXMLCreator { return null; } + /** + * get the leeward gate in a race + * @param reader reads in the mark + * @return the leeward gate. + */ public static CompoundMark getLeewardGate(RaceXMLReader reader){ for (CompoundMark mark: reader.getCompoundMarks()){ if (mark.getName().equals("Leeward Gate")) return mark; @@ -106,6 +129,15 @@ public class RaceXMLCreator { return null; } + /** + * Rotates the race in a specified direction. + * @param s xml file name + * @param degrees degrees to rotate + * @return the new xml file as a string + * @throws XMLReaderException if the xml is not readable + * @throws InvalidRaceDataException if the race is invalid + * @throws JAXBException if the Race class cannot be parsed into a xml. + */ public static String alterRaceToWind(String s, double degrees) throws XMLReaderException, InvalidRaceDataException, JAXBException { RaceXMLReader reader = new RaceXMLReader(s, XMLFileType.ResourcePath); @@ -127,6 +159,11 @@ public class RaceXMLCreator { return sw.toString(); } + /** + * Rotate the features in a race such as the boundary, and the marks. + * @param race the race to alter + * @param degrees the degrees to rotate by. + */ public static void alterRaceRotation(Race race, double degrees){ GPSCoordinate center = getCenter(race); for(Race.CourseLimit.Limit limit: race.getCourseLimit().getLimit()){ @@ -145,10 +182,22 @@ public class RaceXMLCreator { } } + /** + * Converts a Race.CourseLimit.Limit to a GPS coordinate + * @param limit limit to convert + * @return gps coordinate corresponding to the limit + */ public static GPSCoordinate limitToGPSCoordinate(Race.CourseLimit.Limit limit){ return new GPSCoordinate(Double.parseDouble(limit.getLat()), Double.parseDouble(limit.getLon())); } + /** + * get new gps coordinate after rotating + * @param pivot center point to rotating from. + * @param point point to rotate + * @param degrees number of degress to rotate by + * @return the new GPSCoordinate of the transformed point. + */ public static GPSCoordinate rotate(GPSCoordinate pivot, GPSCoordinate point, double degrees){ double radDeg = Math.toRadians(degrees); double deltaLat = (point.getLatitude() - pivot.getLatitude()); @@ -159,10 +208,20 @@ public class RaceXMLCreator { return new GPSCoordinate(resLat, resLon); } + /** + * obtains the GPSCoordinates of a mark + * @param mark mark to obtain the GPSCoordinates of + * @return the GPSCOordinatess of a mark + */ public static GPSCoordinate markToGPSCoordinate(Race.Course.CompoundMark.Mark mark){ return new GPSCoordinate(Double.parseDouble(mark.getTargetLat()), Double.parseDouble(mark.getTargetLng())); } + /** + * get the center of a race + * @param race race to get the center of + * @return GPSCoordinates of the center + */ public static GPSCoordinate getCenter(Race race){ double avgLat = 0; double avgLng = 0; @@ -174,6 +233,13 @@ public class RaceXMLCreator { avgLng = avgLng/race.getCourseLimit().getLimit().size(); return new GPSCoordinate(avgLat, avgLng); } + + /** + * gets the angle of a line + * @param coord1 point a of the line + * @param coord2 point b of the line + * @return the angle in degrees that the bearing of the line is [-180, 180] + */ public static double getLineAngle(GPSCoordinate coord1, GPSCoordinate coord2){ double dx = coord1.getLongitude() - coord2.getLongitude(); double dy = coord1.getLatitude() - coord2.getLatitude();