अपने ऐप्लिकेशन में 3D मैप जोड़ना

यह प्रॉडक्ट या सुविधा, एक्सपेरिमेंट के तौर पर उपलब्ध है (pre-GA). हो सकता है कि Pre-GA के तहत आने वाले प्रॉडक्ट और सुविधाओं के लिए, आपको पूरी सहायता न मिले. साथ ही, ऐसा हो सकता है कि Pre-GA के तहत आने वाले प्रॉडक्ट और सुविधाओं में किए गए बदलाव, Pre-GA के अन्य वर्शन के साथ काम न करें. Pre-GA ऑफ़र पर, Google Maps Platform की सेवा से जुड़ी खास शर्तें लागू होती हैं. ज़्यादा जानकारी के लिए, लॉन्च के चरणों की जानकारी देखें.

प्लैटफ़ॉर्म चुनें: Android iOS JavaScript

इस पेज पर, Android के लिए Maps 3D SDK का इस्तेमाल करके, Android ऐप्लिकेशन में बुनियादी 3D मैप जोड़ने का तरीका बताया गया है. इस पेज पर दिए गए निर्देशों में यह माना गया है कि आपने सेटअप वाले पेज पर दिए गए चरण पूरे कर लिए हैं और आपके पास ये चीज़ें मौजूद हैं:

• Google Cloud का ऐसा प्रोजेक्ट जिसमें Android के लिए Maps 3D SDK चालू हो
• Android के लिए Maps 3D SDK के साथ इस्तेमाल करने के लिए कॉन्फ़िगर की गई API (एपीआई) कुंजी
• Android के लिए Maps 3D SDK के साथ इस्तेमाल करने के लिए सेट अप किया गया Android Studio प्रोजेक्ट

इन ज़रूरी शर्तों के बारे में ज़्यादा जानने के लिए, सेटअप देखें.

पहला चरण: Map3DView कॉम्पोनेंट जोड़ने के लिए, लेआउट फ़ाइल (activity_main.xml) अपडेट करना

Map3DView कॉम्पोनेंट, वह व्यू है जो ऐप्लिकेशन में 3D मैप रेंडर करता है. यहां दिए गए चरणों से, कॉम्पोनेंट जोड़ा जाता है और मैप की शुरुआती स्थिति कॉन्फ़िगर की जाती है. इसमें कैमरे की पोज़िशन और उससे जुड़े एट्रिब्यूट शामिल होते हैं:

ध्यान दें: इस सेक्शन में दिए गए चरणों में यह माना गया है कि आपने सेटअप में बताए गए तरीके का इस्तेमाल करके, अपना Android Studio प्रोजेक्ट बनाया और कॉन्फ़िगर किया है. इसके अलावा, यह भी माना गया है कि आपने किसी मौजूदा प्रोजेक्ट में, नया व्यू ऐक्टिविटी जोड़ा है. अगर आपने व्यू ऐक्टिविटी जोड़े बिना, नया Android Studio प्रोजेक्ट बनाया है, तो आपके प्रोजेक्ट में activity_main.xml फ़ाइल नहीं होगी.

1. अपनी मुख्य ऐक्टिविटी की लेआउट फ़ाइल खोलें. यह आम तौर पर, app/src/main/res/layout/activity_main.xml पर मौजूद होती है.

2. रूट ConstraintLayout (या अपने रूट लेआउट एलिमेंट) में, map3d एक्सएमएल नेमस्पेस जोड़ें:

   xmlns:map3d="http://schemas.android.com/apk/res-auto"
   

3. डिफ़ॉल्ट <TextView> मिटाएं, जो "Hello World!" दिखाता है.

4. अपने लेआउट में Map3DView कॉम्पोनेंट जोड़ें. कैमरे की पोज़िशन और अन्य एट्रिब्यूट को पसंद के मुताबिक बनाया जा सकता है:

   <?xml version="1.0" encoding="utf-8"?>
   <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
     android:id="@+id/main"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     tools:context=".MainActivity">
   
     <com.google.android.gms.maps3d.Map3DView
       android:id="@+id/map3dView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       map3d:mode="hybrid"
       map3d:centerLat="38.544012"
       map3d:centerLng="-107.670428"
       map3d:centerAlt="2427.6"
       map3d:heading="310"
       map3d:tilt="63"
       map3d:range="8266"
       map3d:roll="0"
       map3d:minAltitude="0"
       map3d:maxAltitude="1000000"
       map3d:minHeading="0"
       map3d:maxHeading="360"
       map3d:minTilt="0"
       map3d:maxTilt="90"
       app:layout_constraintBottom_toBottomOf="parent"
       app:layout_constraintEnd_toEndOf="parent"
       app:layout_constraintStart_toStartOf="parent"
       app:layout_constraintTop_toTopOf="parent" />
   </androidx.constraintlayout.widget.ConstraintLayout>
   

दूसरा चरण: MainActivity.kt अपडेट करना

यहां दिए गए चरणों से, पहले चरण में activity_main.xml फ़ाइल में जोड़े गए Map3DView कॉम्पोनेंट को शुरू किया जाता है. साथ ही, कॉम्पोनेंट के लाइफ़साइकल इवेंट मैनेज किए जाते हैं.

ध्यान दें कि Android के लिए Maps 3D SDK, एक समय पर सिर्फ़ एक चालू Map3DView इंस्टेंस के साथ काम करता है. एक साथ कई Map3DView इंस्टेंस दिखाना (जैसे, एक ही लेआउट या अलग-अलग दिखने वाली ऐक्टिविटी या फ़्रैगमेंट में) काम नहीं करता.इससे रेंडरिंग से जुड़ी समस्याएं हो सकती हैं. जैसे, सेकंडरी व्यू में काली स्क्रीन दिखना.

इसके अलावा, सभी Map3DView एक ही मैप की स्थिति शेयर करेंगे और दिखाएंगे.जैसे, कैमरे की पोज़िशन, जोड़े गए मार्कर, पॉलीगॉन वगैरह. अगर Map3DView को onDestroy का इस्तेमाल करके मिटा दिया जाता है और दूसरा बनाया जाता है, तब भी मैप की स्थिति बनी रहेगी. हालांकि, इसे मैन्युअल तरीके से मिटाया जा सकता है. उदाहरण के लिए, अगर आपने Map3DView1 में मार्कर जोड़े हैं, तो उसे मिटाने और Map3DView2 बनाने पर, वे मार्कर Map3DView2 में भी मौजूद रहेंगे.

डेवलपर की ज़िम्मेदारियां:

• एक समय पर एक व्यू: पक्का करें कि किसी भी समय, आपके व्यू के क्रम में सिर्फ़ एक Map3DView चालू हो.
• मैन्युअल तरीके से साफ़ करना: एक Map3DView (जैसे, Map3DView1) से दूसरे (जैसे, Map3DView2) पर स्विच करते समय, आपको पुराने इंस्टेंस (Map3DView1) पर onDestroy() को कॉल करना होगा. ऐसा इसलिए, क्योंकि मैप की स्थिति शेयर की जाती है. इसलिए, यह पक्का करने के लिए कि Map3DView2 नई या खास स्थिति से शुरू हो, आपको Map3DView1 से सेट की गई किसी भी स्थिति को मैन्युअल तरीके से साफ़ करना होगा. इसमें मार्कर, ओवरले वगैरह हटाना और OnMap3DViewReadyCallback में मिले GoogleMap3D ऑब्जेक्ट का इस्तेमाल करके, कैमरे की पोज़िशन रीसेट करना शामिल है.

1. अपनी MainActivity.kt फ़ाइल खोलें. यह आम तौर पर, app/src/main/java/com/example/yourpackagename/MainActivity.kt पर मौजूद होती है.

2. Android के लिए Maps 3D SDK के लिए ज़रूरी इंपोर्ट जोड़ें:

   import com.google.android.gms.maps3d.GoogleMap3D
   import com.google.android.gms.maps3d.Map3DView
   import com.google.android.gms.maps3d.OnMap3DViewReadyCallback
   

3. OnMap3DViewReadyCallback को लागू करने के लिए, MainActivity क्लास में बदलाव करें:

   class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
   

4. Map3DView और GoogleMap3D के लिए वैरिएबल का एलान करें:

   private lateinit var map3DView: Map3DView
   private var googleMap3D: GoogleMap3D? = null
   

5. onCreate तरीके में, setContentView(...) और ViewCompat.setOnApplyWindowInsetsListener ब्लॉक के बाद, map3DView को शुरू करें. इसके लाइफ़साइकल के onCreate तरीके को कॉल करें और एसिंक्रोनस तरीके से मैप का अनुरोध करें:

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       enableEdgeToEdge()
       setContentView(R.layout.activity_main)
       ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
           val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
           v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
           insets
       }
   
       map3DView = findViewById(R.id.map3dView)
       map3DView.onCreate(savedInstanceState)
       map3DView.getMap3DViewAsync(this)
   }
   

6. onMap3DViewReady तरीके को बदलें. जब मैप इस्तेमाल के लिए तैयार हो जाता है, तब यह कॉलबैक ट्रिगर होता है:

   override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
       // Interact with the googleMap3D object here
       this.googleMap3D = googleMap3D
       // You can now make calls to the googleMap3D object, e.g.,
       // googleMap3D.cameraController.flyTo(camera { ... })
   }
   

7. अपनी ऐक्टिविटी से Map3DView में लाइफ़साइकल इवेंट फ़ॉरवर्ड करने के लिए, MainActivity में ये बदलाव जोड़ें:

   override fun onStart() {
       super.onStart()
       map3DView.onStart()
   }
   
   override fun onResume() {
       super.onResume()
       map3DView.onResume()
   }
   
   override fun onPause() {
       map3DView.onPause()
       super.onPause()
   }
   
   override fun onStop() {
       map3DView.onStop()
       super.onStop()
   }
   
   override fun onDestroy() {
       map3DView.onDestroy()
       super.onDestroy()
   }
   
   override fun onSaveInstanceState(outState: Bundle) {
       super.onSaveInstanceState(outState)
       map3DView.onSaveInstanceState(outState)
   }
   
   override fun onLowMemory() {
       super.onLowMemory()
       map3DView.onLowMemory()
   }
   

तीसरा चरण: Gradle को सिंक करना और ऐप्लिकेशन चलाना

अब आपने अपने ऐप्लिकेशन का लेआउट और ऐक्टिविटी अपडेट कर ली है. इसके बाद, 3D मैप व्यू देखने के लिए, ऐप्लिकेशन बनाया और चलाया जा सकता है.

1. अपने प्रोजेक्ट को Gradle के साथ सिंक करने के लिए, फ़ाइल > Gradle फ़ाइलों के साथ प्रोजेक्ट सिंक करें को चुनें.

2. एम्युलेटर या फ़िज़िकल डिवाइस पर अपना ऐप्लिकेशन बनाने और चलाने के लिए, चलाएं > चलाएं को चुनें.

अगर सब कुछ सही तरीके से कॉन्फ़िगर किया गया है, तो आपको अपने ऐप्लिकेशन में 3D मैप दिखेगा. यह मैप, आपके activity_main.xml में बताए गए निर्देशांकों के आस-पास दिखेगा.

अगले चरण

अब आपने अपने ऐप्लिकेशन में बुनियादी 3D मैप जोड़ लिया है. इसके बाद, Android के लिए Maps 3D SDK की ज़्यादा बेहतर सुविधाओं को एक्सप्लोर किया जा सकता है. जैसे,कैमरे के पाथ ऐनिमेशन,3D मार्कर यापॉलीगॉन.

मैप पर क्लिक करने के इवेंट सुनना

मैप पर क्लिक करने के इवेंट सुनने के लिए, GoogleMap3D.setMap3DClickListener का इस्तेमाल करें. जब कोई उपयोगकर्ता मैप पर क्लिक करता है, तो यह लिसनर ट्रिगर होता है. साथ ही, क्लिक किए गए पॉइंट की जगह और प्लेस आईडी की जानकारी मिलती है.

यहां दिए गए उदाहरण में, मैप पर क्लिक करने का लिसनर सेट करने का तरीका बताया गया है:

googleMap3D.setMap3DClickListener { location, placeId ->
    lifecycleScope.launch(Dispatchers.Main) {
        if (placeId != null) {
            Toast.makeText(this@MainActivity, "Clicked on place with ID: $placeId", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this@MainActivity, "Clicked on location: $location", Toast.LENGTH_SHORT).show()
        }
    }
}

ध्यान दें कि क्लिक हैंडलर, मुख्य (या यूज़र इंटरफ़ेस (यूआई)) थ्रेड पर नहीं चलता. अगर आपको यूज़र इंटरफ़ेस (यूआई) में बदलाव करने हैं, तो आपको मुख्य थ्रेड पर स्विच करना होगा. जैसे, Toast मैसेज दिखाना. Kotlin के लिए, lifecycleScope.launch(Dispatchers.Main) का इस्तेमाल करके ऐसा किया जा सकता है.