Merge e73617c2f4 into a94f8f0e32

Doc/add contributing

CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Introduction
+
+Thank you for your interest in DZGUI!
+
+This guide goes over development conventions and best practices for contributors.
+If you are a developer, you can skip to the end.
+
+# Requesting help
+
+If you encounter a problem with DZGUI, you can submit tickets on the GitHub
+(issue tracker)[https://github.com/aclist/dzgui-devel/issues] under the
+`troubleshooting` tag.
+
+# How can I help the project?
+
+There are several ways to help this project.
+1. Report bugs that you find
+2. Request features that you would like
+3. Contribute features and fixes to the codebase
+4. Contribute documentation to the project
+
+Before making any contribution, please read the `CODE_OF_CONDUCT.md` and act
+accordingly.
+
+## Submitting a ticket
+
+Navigate to the GitHub (issue tracker)[https://github.com/aclist/dzgui-devel/issues].
+From there, follow the onscreen prompts. You will be asked questions such as:
+
+- What version are you using?
+- What distribution are you using?
+- What is the issue that you found?
+- How can we reproduce the issue?
+
+You can also attach screenshots, logs, or other data that can help us.
+
+## Requesting a feature
+
+You can also request features via the same issue tracker. It is good practice to
+first search for your idea to see if a similar one has already been posted.
+If not, open a ticket where you describe your feature and its possible benefits.
+
+Please note that this is a community project, so it takes time for us to develop
+features. Putting in a feature request does not mean that it will be implemented,
+but we will do our best to support as many cool ideas as possible.
+
+## Contributing code or documentation
+
+If you would like to take ownership or assist with an issue on the issue tracker, or
+contribute a new change, please follow the guidelines below.
+
+Fork this repository and check out the code up to `prerelease/<latest-version>`.
+If there is no pending prerelease PR, you can base your changes off of
+the `testing` branch. You may later be asked to retarget your PR to the prerelease
+branch once a new one is made. This is because out-of-band PRs are consolidated into
+the next release before merging.
+
+The following naming conventions apply for PRs:
+- fix/<your-fix> - patch/hotfix branches
+- feat/<your-feature> - feature branches
+- doc/<your-doc-branch> - documentation branches
+- infra/<your-infra-branch> - infrastructure branches
+
+Implement your changes and test them locally. If they work you may
+open a merge request, and then we review your changes. If everything is OK, it
+will be merged to `prerelease/<latest-version>`, then `testing`, and after a live
+testing phase, to `stable` as well.
+
+It is recommended to follow
+(Conventional Commits)[https://www.conventionalcommits.org/en/v1.0.0/], as this
+integrates well with tooling and helps the project review your code.

helpers/latlon.c

@@ -1,36 +0,0 @@
-#include <stdio.h>
-#include <stdlib.h>
-#include <math.h>
-
-#define R 6371
-#define TO_RAD (3.1415926536 / 180)
-double dist(double th1, double ph1, double th2, double ph2)
-{
-	double dx, dy, dz;
-	ph1 -= ph2;
-	ph1 *= TO_RAD, th1 *= TO_RAD, th2 *= TO_RAD;
-
-	dz = sin(th1) - sin(th2);
-	dx = cos(ph1) * cos(th1) - cos(th2);
-	dy = sin(ph1) * cos(th1);
-	return asin(sqrt(dx * dx + dy * dy + dz * dz) / 2) * 2 * R;
-}
-
-int main(int argc, const char * argv[])
-{
-	if(argc < 5 || argc > 5){
-		return 1;
-	}
-	float coords[4];
-	for(int i=1;i<5;i++){
-		if(atof(argv[i]) == 0){
-			return 1;
-		}
-		coords[i] = atof(argv[i]);
-	}
-	
-	double d = dist(coords[1], coords[2], coords[3], coords[4]);
-	printf("%.1f\n", d);
-
-	return 0;
-}

helpers/tools/.gitignore

@@ -0,0 +1 @@
+latlon

helpers/tools/Makefile

@@ -0,0 +1,24 @@
+bin := latlon
+
+CC = gcc
+
+CFLAGS += -Wall
+CFLAGS += -Wextra
+CFLAGS += -Wpedantic
+CFLAGS += -std=c23
+CFLAGS += -O3
+
+LDFLAGS += -lm
+
+PREFIX ?= $(HOME)/.local/share/dzgui
+
+all: $(bin)
+
+install: $(bin)
+	install -Dm 755 $(bin) $(PREFIX)
+
+$(bin): latlon.c
+	$(CC) $(CFLAGS) $^ -o $@ $(LDFLAGS)
+
+clean:
+	rm -f $(bin)

helpers/tools/latlon.c

@@ -0,0 +1,74 @@
+// This small program computes the distance between two points on the Earths
+// surface. The algorithm used for computing is called haversine formula.
+// Source for the algorithm can be found here:
+// https://en.wikipedia.org/wiki/Haversine_formula
+
+#include <math.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+// Earths radius in meters
+#define RADIUS ((12756L / 2.0L) * 1000L)
+
+// PI natural constant
+#define PI 3.1415926536L
+
+// coordinates struct for storing points
+struct Coordinate {
+    double latitude;
+    double longitude;
+};
+
+/**
+ * @brief Calculates a radian value from an angle
+ */
+double radian_from(const double angle) {
+    return (angle * PI) / 180;
+}
+
+/**
+ * @brief Calculate the haversine function from an angle in radian
+ */
+double haversine(const double angle) { return ((1.0L - cos(angle)) / 2); }
+
+/**
+ * @brief Calculate the distance between two coordinates
+ */
+double great_circle_distance(const struct Coordinate a,
+                             const struct Coordinate b) {
+
+    // calculate longitude and latitude differences
+    struct Coordinate diff_coord = {
+        .longitude = a.longitude - b.longitude,
+        .latitude  = a.latitude - b.latitude,
+    };
+
+    // calculate haversine(theta) value, where theta is the angle between the
+    // two coordinates
+    double hav_theta = haversine(diff_coord.latitude)
+                       + cos(a.latitude) * cos(b.latitude) * haversine(diff_coord.longitude);
+
+    // calculate distance from radius, and haversine(theta) values 
+    double distance = 2 * RADIUS * asin(sqrt(hav_theta));
+
+    return distance;
+}
+
+int main(int argc, const char* argv[]) {
+    if (argc < 5 || argc > 5) {
+        return 1;
+    }
+
+    const struct Coordinate a = {
+        .latitude  = radian_from(atof(argv[1])),
+        .longitude = radian_from(atof(argv[2])),
+    };
+    const struct Coordinate b = {
+        .latitude  = radian_from(atof(argv[3])),
+        .longitude = radian_from(atof(argv[4])),
+    };
+
+    printf("%.1f\n", great_circle_distance(a, b));
+
+    return 0;
+}