chore(heatmaps): Port heatmaps package to Kotlin (#1573)

* Rename .java to .kt

* refactor(library): Convert projection.Point to Kotlin and add tests

The `@Deprecated` annotation has been updated to the Kotlin syntax and now includes a `ReplaceWith` expression to provide IDE quick-fix support.

Additionally, new unit tests using Google Truth have been added for the `Point` class to verify its construction and inheritance.

* refactor(heatmaps): Port Gradient and WeightedLatLng to Kotlin

This commit migrates the `Gradient` and `WeightedLatLng` classes and their corresponding tests from Java to idiomatic Kotlin.

This conversion is part of the larger effort to modernize the library and prepare it for Kotlin Multiplatform (KMP) compatibility.

Key changes include:
- `WeightedLatLng` is now a `data class` with a private primary constructor to ensure correct instantiation while providing the benefits of auto-generated methods. The `@ExposedCopyVisibility` annotation has been added to maintain binary compatibility for the `copy()` method.
- `Gradient` has been converted to a Kotlin class, using `@JvmOverloads` for constructor compatibility and a `companion object` for its static helper method.
- The `internal` visibility of a method in `Gradient` was changed to `public` to ensure visibility to Java classes during the mixed-language phase of the migration.
- Unit tests for both classes have been ported to Kotlin, using the Truth assertion framework.

* feat(heatmaps): Port HeatmapTileProvider to Kotlin

This commit completes the migration of the `heatmaps` package to Kotlin by porting the final and most complex class, `HeatmapTileProvider`.

This conversion modernizes the class by introducing several idiomatic Kotlin features and improves its design by refactoring a key data structure.

Key changes include:
- The `HeatmapTileProvider` and its `Builder` are now written in Kotlin.
- The `getMaxValue()` method was refactored to use a `Map` with a type-safe `Vector` key instead of the Android-specific `LongSparseArray`, improving readability and moving closer to KMP compatibility.
- A new test suite was created from scratch for the provider, as none existed previously. This improves the code coverage and reliability of the module.
- Necessary adjustments were made to the demo application to support the newly ported Kotlin class.

* fix(tests): Correct copyright headers in new test files

Updates the copyright headers in the test files that were created
during the Kotlin porting process.

- Corrects the copyright year to 2025.
- Corrects the company name from "Google Inc." to "Google LLC".

* chore: Add PLACES_API_KEY to local.defaults.properties

* fix(heatmaps): Correct copyright headers

Updates the copyright headers in the `heatmaps` package source and test files.

- Corrects the copyright year to 2025.
- Corrects the company name from "Google Inc." to "Google LLC".

* refactor(heatmaps): Improve API clarity and documentation

Addresses feedback to make the heatmap API more intuitive and robust.

- Renames `setWeightedData` and `setData` in `HeatmapTileProvider` to `updateData` and `updateLatLngs` respectively. The `update` prefix better communicates that these methods perform expensive operations that rebuild internal state, rather than just setting a property.
- The old method names are preserved and marked as `@Deprecated` to provide a smooth migration path for existing users and avoid a breaking change.

- Adds a default value of 0.7 to the `opacity` parameter in `Gradient.generateColorMap`. This aligns with the default in `HeatmapTileProvider` and simplifies common use cases.
- Annotates `generateColorMap` with `@JvmOverloads` to ensure the new default parameter is exposed correctly to Java clients.

- Improves KDoc for all modified methods to be more descriptive, explaining the purpose of the code and the reasoning behind the design choices.

* refactor(heatmaps): Use constant for default opacity

Updates the `generateColorMap` function to use the
`HeatmapTileProvider.DEFAULT_OPACITY` constant for its default
opacity value.

This removes a hardcoded value, improving maintainability and ensuring
the default remains consistent with the provider. The accompanying
KDoc has also been corrected.

Author: dkhawk

demo/src/main/java/com/google/maps/android/utils/demo/BaseDemoActivity.java

@@ -28,6 +28,8 @@
 import com.google.android.gms.maps.OnMapReadyCallback;
 import com.google.android.gms.maps.SupportMapFragment;
 
+import java.util.Objects;
+
 public abstract class BaseDemoActivity extends FragmentActivity implements OnMapReadyCallback {
     private GoogleMap mMap;
     private boolean mIsRestore;
@@ -60,7 +62,7 @@ public void onMapReady(@NonNull GoogleMap map) {
     }
 
     private void setUpMap() {
-        ((SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map)).getMapAsync(this);
+        ((SupportMapFragment) Objects.requireNonNull(getSupportFragmentManager().findFragmentById(R.id.map))).getMapAsync(this);
     }
 
     /**

demo/src/main/java/com/google/maps/android/utils/demo/HeatmapsPlacesDemoActivity.java

@@ -19,6 +19,7 @@
 import android.content.Context;
 import android.graphics.Color;
 import android.os.AsyncTask;
+import android.os.Bundle;
 import android.util.Log;
 import android.view.View;
 import android.view.inputmethod.EditorInfo;
@@ -63,6 +64,9 @@ public class HeatmapsPlacesDemoActivity extends BaseDemoActivity {
     private final String TAG = "HeatmapPlacesDemo";
 
     private final LatLng SYDNEY = new LatLng(-33.873651, 151.2058896);
+    private final LatLng BOULDER = new LatLng(40.0216437819216, -105.25471683073081);
+
+    private final LatLng FOCUS = BOULDER;
 
     /**
      * The base URL for the radar search request.
@@ -78,27 +82,28 @@ public class HeatmapsPlacesDemoActivity extends BaseDemoActivity {
     /**
      * Places API server key.
      */
-    private static final String API_KEY = "YOUR_KEY_HERE"; // TODO place your own here!
+    private static final String API_KEY = BuildConfig.PLACES_API_KEY;
 
     /**
      * The colors to be used for the different heatmap layers.
      */
     private static final int[] HEATMAP_COLORS = {
-        HeatmapColors.RED.color,
-        HeatmapColors.BLUE.color,
-        HeatmapColors.GREEN.color,
-        HeatmapColors.PINK.color,
-        HeatmapColors.GREY.color
+            HeatmapColors.RED.color,
+            HeatmapColors.BLUE.color,
+            HeatmapColors.GREEN.color,
+            HeatmapColors.PINK.color,
+            HeatmapColors.GREY.color
     };
 
     public enum HeatmapColors {
-        RED (Color.rgb(238, 44, 44)),
-        BLUE (Color.rgb(60, 80, 255)),
-        GREEN (Color.rgb(20, 170, 50)),
-        PINK (Color.rgb(255, 80, 255)),
-        GREY (Color.rgb(100, 100, 100));
+        RED(Color.rgb(238, 44, 44)),
+        BLUE(Color.rgb(60, 80, 255)),
+        GREEN(Color.rgb(20, 170, 50)),
+        PINK(Color.rgb(255, 80, 255)),
+        GREY(Color.rgb(100, 100, 100));
 
         private final int color;
+
         HeatmapColors(int color) {
             this.color = color;
         }
@@ -115,7 +120,7 @@ public enum HeatmapColors {
     /**
      * Stores the TileOverlay corresponding to each of the keywords that have been searched for.
      */
-    private Hashtable<String, TileOverlay> mOverlays = new Hashtable<String, TileOverlay>();
+    private final Hashtable<String, TileOverlay> mOverlays = new Hashtable<String, TileOverlay>();
 
     /**
      * A layout containing checkboxes for each of the heatmaps rendered.
@@ -132,6 +137,19 @@ public enum HeatmapColors {
      */
     private int mOverlaysInput = 0;
 
+    @Override
+    public void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        if ("YOUR_API_KEY".equals(API_KEY)) {
+            Toast.makeText(
+                    this,
+                    "Please sign up for a Places API key and add it to HeatmapsPlacesDemoActivity.API_KEY",
+                    Toast.LENGTH_LONG
+            ).show();
+            finish();
+        }
+    }
+
     @Override
     protected int getLayoutId() {
         return R.layout.places_demo;
@@ -152,11 +170,11 @@ protected void startDemo(boolean isRestore) {
         mCheckboxLayout = findViewById(R.id.checkboxes);
         GoogleMap map = getMap();
         if (!isRestore) {
-            map.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 11));
+            map.moveCamera(CameraUpdateFactory.newLatLngZoom(FOCUS, 11));
         }
-        // Add a circle around Sydney to roughly encompass the results
+        // Add a circle around FOCUS to roughly encompass the results
         map.addCircle(new CircleOptions()
-                .center(SYDNEY)
+                .center(FOCUS)
                 .radius(SEARCH_RADIUS * 1.2)
                 .strokeColor(Color.RED)
                 .strokeWidth(4));
@@ -167,18 +185,13 @@ protected void startDemo(boolean isRestore) {
      * Called when a search query is submitted
      */
     public void submit(View view) {
-        if ("YOUR_KEY_HERE".equals(API_KEY)) {
-            Toast.makeText(this, "Please sign up for a Places API key and add it to HeatmapsPlacesDemoActivity.API_KEY",
-                Toast.LENGTH_LONG).show();
-            return;
-        }
         EditText editText = findViewById(R.id.input_text);
         String keyword = editText.getText().toString();
         if (mOverlays.contains(keyword)) {
             Toast.makeText(this, "This keyword has already been inputted :(", Toast.LENGTH_SHORT).show();
         } else if (mOverlaysRendered == MAX_CHECKBOXES) {
             Toast.makeText(this, "You can only input " + MAX_CHECKBOXES + " keywords. :(", Toast.LENGTH_SHORT).show();
-        } else if (keyword.length() != 0) {
+        } else if (!keyword.isEmpty()) {
             mOverlaysInput++;
             ProgressBar progressBar = findViewById(R.id.progress_bar);
             progressBar.setVisibility(View.VISIBLE);
@@ -202,11 +215,11 @@ public void submit(View view) {
     private Collection<LatLng> getPoints(String keyword) {
         HashMap<String, LatLng> results = new HashMap<>();
 
-        // Calculate four equidistant points around Sydney to use as search centers
+        // Calculate four equidistant points around FOCUS to use as search centers
         //   so that four searches can be done.
         ArrayList<LatLng> searchCenters = new ArrayList<>(4);
         for (int heading = 45; heading < 360; heading += 90) {
-            searchCenters.add(SphericalUtil.computeOffset(SYDNEY, SEARCH_RADIUS / 2, heading));
+            searchCenters.add(SphericalUtil.computeOffset(FOCUS, (double) SEARCH_RADIUS / 2, heading));
         }
 
         for (int j = 0; j < 4; j++) {