Bagaimana Saya Membina Kompas Arah Kiblat

Baru-baru ni, saya gatal tangan pergi buat satu Kompas Arah Kiblat untuk AkuIslam.

Bunyinya macam saya bangun pagi, buka laptop, kemudian terus berubah menjadi programmer. Tapi hakikatnya, saya ni bukan seorang programmer pun.

Saya cuma orang tua yang dah terlalu lama menjaga website sampai terpaksa memahami benda-benda di alam sebalik tabir seperti DNS, Cloudflare, PHP, JavaScript dan cache invalidation.

Masa darjah satu dulu, kalau cikgu tanya cita-cita, tak adanya saya nak tulis, “Bila besar nanti saya mahu troubleshoot cache, cikgu.”

Tetapi begitulah hidup. Kita merancang hendak menjadi orang biasa. Tiba-tiba pada tahun 2026 kita sedang berbahas dengan dua AI tentang sensor magnetometer telefon. 🤣

Objektif asal saya sebenarnya mudah: saya mahu AkuIslam mempunyai satu alat arah kiblat yang jelas, jujur tentang hadnya dan cukup boleh dipercayai untuk saya sendiri gunakan.

Daripada Tempat Membaca Kepada Tempat Menyelesaikan Sesuatu

Selama ini AkuIslam pada asasnya ialah tempat orang datang membaca. Mereka mahu belajar solat, doa, ibadah dan pelbagai perkara asas agama.

Saya mula terfikir bahawa sebuah website tidak semestinya hanya menjadi tempat membaca. Ia juga boleh menjadi tempat orang menyelesaikan sesuatu.

Nak tahu arah kiblat? Buka halaman, benarkan lokasi, dapat jawapan. Tak perlu pasang aplikasi. Tak perlu cuba membaca peta sambil memusing telefon macam sedang mencari siaran radio.

Tool arah kiblat bukan teknologi baharu. Aplikasi seumpamanya sudah ada beratus-ratus. Saya bukan Archimedes yang baru keluar dari tab mandi sambil menjerit Eureka.

Matlamat saya lebih kecil, tetapi bagi saya lebih bermakna: membina AkuIslam Tools sedikit demi sedikit, supaya AkuIslam bukan sahaja menerangkan ibadah tetapi turut menyediakan kemudahan yang berguna untuk melaksanakannya.

Masalahnya, sebaik sahaja kita menggunakan perkataan “boleh dipercayai”, kerja yang nampak kecil mula menunjukkan perangai sebenar.

Masalah Pertama: Kiblat Bukan Garis Lurus Di Atas Peta

Sistem perlu mengetahui dua titik:

• Titik pertama ialah lokasi pengguna dalam bentuk latitud dan longitud.
• Titik kedua ialah koordinat Kaabah yang kami tetapkan pada 21.422487° utara dan 39.826206° timur.

Daripada dua koordinat itu, sistem mengira initial great-circle bearing^[1]: iaitu sudut permulaan bagi laluan terpendek di permukaan bumi menuju ke Kaabah, diukur mengikut arah jam dari utara benar.

Sebab itulah kita tak boleh sekadar menarik satu garisan lurus di atas peta rata.

Peta ialah gambaran dua dimensi, sedangkan bumi mempunyai kelengkungan.

Maaf ya kepada golongan pentaksub bumi rata. Saya sudah cuba menjaga hati, tetapi trigonometri tidak memberi kerjasama. 🤣

Di belakang satu nombor seperti 292° itu ada latitud dalam radian, perbezaan longitud, sine, cosine dan atan2^[2]. Hasil akhirnya kemudian dinormalisasikan ke dalam julat 0° hingga 360°.

Bagi kebanyakan lokasi di Malaysia, hasilnya berada sekitar 291° hingga 293°. Itu bukan nombor yang dipilih kerana nampak munasabah. Ia keluar daripada koordinat pengguna dan koordinat Kaabah melalui fungsi pengiraan yang sama setiap kali.

Saya suka bahagian ini kerana ia mengubah persoalan “anak panah tu macam betul kot” kepada sesuatu yang boleh diuji: jika input koordinat sama, bearing mestilah sama.

Arah Dan Jarak Ialah Dua Masalah Berbeza

Dalam proses membina tool ini, saya sedar satu perkara yang mudah terlepas pandang: mengira arah dan mengira jarak bukan masalah yang sama.

Untuk arah kiblat, plugin menggunakan initial great-circle bearing berasaskan trigonometri sfera. Untuk paparan jarak ke Kaabah pula, kami menggunakan formula Lambert^[3] pada model bumi elipsoid WGS84^[4].

WGS84 ialah sistem rujukan koordinat global yang digunakan oleh GPS. Model ini tidak menganggap bumi sebagai bola sempurna; bentuknya sedikit leper pada kutub.

Kenapa bersusah payah menggunakan Lambert untuk jarak? Kerana model sfera mudah memberikan kira-kira 6,974 km bagi Kuala Lumpur ke Kaabah, sedangkan jarak geodesik WGS84 berada sekitar 6,979 km. Beza lima kilometer itu tidak mengubah arah kiblat, tetapi cukup besar untuk membuat orang yang menyemak nombor menyangka tool kita silap.

Dalam ujian projek, pengiraan Lambert itu dibandingkan dengan GeographicLib dan kekal dalam ralat kurang daripada 51 meter bagi jarak di bawah 15,000 km. Saya bukan hendak pengguna mengagumi formula tersebut. Saya cuma tidak mahu nombor sampingan yang cuai merosakkan kepercayaan terhadap nombor utama.

Satu keputusan penting dalam projek ini ialah tidak mencampurkan semua matematik di bawah satu label “kiraan kiblat”. Arah ada kaedahnya. Jarak ada kaedahnya. Sensor pula masalah yang lain sama sekali.

Bearing Statik Dahulu, Live Compass Kemudian

Saya sengaja menjadikan bearing statik sebagai rujukan utama. Live compass hanyalah progressive enhancement^[5]: kemudahan tambahan apabila telefon dan pelayar mempunyai sensor yang sesuai.

Ini penting kerana nombor bearing dan jarum kompas datang daripada dua jenis maklumat yang berbeza.

• Bearing kiblat datang daripada koordinat pengguna dan koordinat Kaabah.
• Heading telefon datang daripada sensor orientasi, magnetometer dan cara pelayar mendedahkan data tersebut.
• Arah relatif ialah beza paling pendek antara bearing kiblat dengan heading telefon semasa.

Bearing boleh dikira walaupun komputer tidak mempunyai magnetometer. Live compass pula boleh gagal walaupun GPS berjaya. Sebab itu kedua-duanya tidak patut dipaksa menjadi satu benda.

Kalau sensor tidak tersedia, pengguna masih mendapat angka arah dari utara benar dan kompas statik. Tool tidak berlakon seolah-olah semua peranti mempunyai keupayaan yang sama.

iPhone Dan Android Tidak Bercakap Bahasa Yang Sama

Bahagian yang paling banyak memberikan character development ialah perbezaan antara iPhone dan Android.

Pada iOS 13 dan ke atas, akses kepada sensor orientasi perlu diminta melalui DeviceOrientationEvent.requestPermission()^[6], dan permintaan itu mesti berlaku ketika pengguna benar-benar menekan butang. Jika kita menunggu proses geolocation selesai dahulu, konteks sentuhan pengguna sudah hilang dan iOS boleh menolak permintaan tersebut.

Jadi apabila pengguna menekan “Mulakan”, plugin memulakan permintaan lokasi dan kebenaran sensor serentak. Kebenaran sensor disimpan sementara bearing dikira. Apabila kedua-duanya tersedia, barulah live compass diaktifkan.

Untuk laluan WebKit^[7] pada iPhone, plugin mengutamakan webkitCompassHeading. Apple mentakrifkannya sebagai arah dalam darjah relatif kepada utara magnet, dan WebKit turut boleh memberikan webkitCompassAccuracy sebagai anggaran ketepatan.

Android Chrome pula lazimnya memberikan deviceorientationabsolute^[8] dengan nilai alpha, beta dan gamma. Plugin hanya menerima sumber yang benar-benar absolute. Jika pelayar sekadar memberikan orientation relatif terhadap kedudukan awal telefon, ia ditolak kerana itu bukan kompas sebenar.

Masalahnya, laluan Android itu tidak memberikan metrik ketepatan yang setara dengan webkitCompassAccuracy. JavaScript boleh membaca heading, tetapi tidak semestinya tahu sama ada magnetometer sedang tersasar. Maka sistem memilih untuk meminta pengguna menentukur telefon terlebih dahulu, bukan berdiam diri dan berpura-pura yakin.

Di sinilah satu batas penting perlu disebut dengan jujur. Bearing kiblat dikira dari utara benar, manakala webkitCompassHeading pada iPhone merujuk utara magnet. Versi semasa belum membundel pembetulan deklinasi World Magnetic Model^[9]. Oleh itu, bearing statik kekal sumber rujukan utama dan live compass dilabel sebagai anggaran sensor.

Ini bukan ayat marketing yang sedap. Tetapi saya lebih rela tool mengaku hadnya daripada memberikan keyakinan palsu dengan animasi yang nampak meyakinkan.

Untuk ujian fizikal, laluan utama telah dicuba pada iPhone 14 menggunakan Safari dan sebuah telefon Xiaomi menggunakan Chrome. Pelayar iPhone lain menggunakan enjin WebKit yang sama, tetapi itu tidak bermakna saya patut mendakwa semua kombinasi peranti sudah diuji.

Telefon Mesti Tahu “Atas” Itu Di Mana

Sensor orientasi tidak terus menghantar ayat, “Telefon sedang menghadap 292 darjah.” Ia memberikan tiga sudut Euler^[10]: alpha, beta dan gamma.

Alpha mewakili putaran pada paksi menegak. Beta dan gamma pula membantu kita memahami kecondongan telefon. Dalam postur yang disokong, telefon dipegang hampir mendatar dengan skrin menghadap ke atas, dan arah bahagian atas skrin boleh diperoleh daripada -alpha.

Plugin juga mengambil kira orientasi skrin apabila telefon diputar ke landscape. Tetapi kami tidak membenarkan semua postur sesuka hati. Apabila kecondongan melebihi 40°, bacaan alignment dihentikan sementara dan pengguna diminta meratakan telefon.

Kenapa begitu tegas? Kerana versi awal formula heading pernah mempunyai discontinuity. Perubahan pose yang sangat kecil boleh menyebabkan heading melompat sehingga 180° apabila kod bertukar antara dua vektor rujukan.

Penyelesaiannya bukan menambah lebih banyak tampalan. Pendekatan dua vektor itu dibuang. Kami menyokong satu postur yang jelas, menggunakan model orientasi yang lebih ringkas, dan berhenti apabila syarat postur tidak dipenuhi.

Kadang-kadang sistem menjadi lebih boleh dipercayai bukan kerana ia mampu melakukan semuanya, tetapi kerana ia mengecilkan kawasan di mana ia sanggup berkata, “Ya, bacaan ini boleh digunakan.”

Kes 359° Lawan 1°

Kemudian datang masalah kegemaran saya: 359 darjah lawan 1 darjah.

Kalau matematik kedai runcit, 359 tolak 1 bersamaan 358. Tetapi pada bulatan kompas, jarak paling pendek antara dua sudut itu cuma 2 darjah.

Sebab itu semua perbezaan sudut dinormalisasikan ke julat -180° hingga 180°. Nilai positif bermaksud kiblat berada di sebelah kanan. Nilai negatif bermaksud pengguna perlu berpusing ke kiri.

Smoothing^[11] juga tidak boleh menggunakan purata biasa. Purata 359° dan 1° secara aritmetik ialah 180°, iaitu arah yang bertentangan. Jadi plugin melicinkan bacaan melalui komponen sine dan cosine dengan faktor 0.18, kemudian menukarnya semula kepada sudut.

Untuk animasi pula, sistem sentiasa memilih laluan putaran terpendek. Jarum yang melintasi sempadan utara tidak sepatutnya berpusing hampir satu bulatan penuh hanya kerana nombor berubah daripada 359 kepada 0.

Saya tak sangka satu hari nanti saya akan menulis tentang circular smoothing dalam blog peribadi. Tetapi di sinilah kita sekarang.

Bila Sistem Patut Mengaku “Tepat”?

Menunjukkan jarum ialah satu perkara. Memutuskan bila pengguna sudah menghadap kiblat ialah perkara lain.

Kalau ambangnya satu nombor sahaja, bacaan sensor yang bergetar di sempadan boleh membuat warna dan mesej berkelip-kelip. Jadi plugin menggunakan hysteresis^[12]: ambang masuk dan ambang keluar yang berbeza.

• Dalam lingkungan 20°, sistem memberitahu pengguna bahawa mereka sudah menghampiri arah kiblat; keadaan itu hanya dilepaskan selepas melebihi 22°.
• Dalam lingkungan 10°, panduan meminta pengguna memperlahankan pergerakan; ia keluar selepas melebihi 12°.
• Dalam lingkungan 5°, kompas menjadi hijau dan ikon Kaabah muncul; keadaan sejajar hanya dilepaskan selepas melebihi 8°.

Tetapi satu lintasan pantas melalui 5° tidak patut terus dianggap pengesahan. Jadi terdapat lapisan kedua: pengguna mesti kekal dalam lingkungan 5° selama satu saat penuh sebelum mesej “Arah kiblat tepat” dan getaran diberikan.

Ringkasnya, hijau bermaksud “anda sedang berada dalam zon yang betul”. Pengesahan bermaksud “anda benar-benar memegang arah itu”.

Perbezaan kecil ini mengambil banyak perbincangan. Begitulah nasib kita apabila cuba menentukan makna satu warna hijau dengan penuh tanggungjawab.

Kalibrasi, Magnet Dan Perangai Dunia Sebenar

Telefon bukan alat ukur makmal. Magnetometer^[13] boleh terganggu oleh casing bermagnet, pembesar suara, besi meja, kereta, struktur bangunan dan macam-macam benda yang pengguna tidak nampak.

Pada laluan WebKit, jika webkitCompassAccuracy negatif atau melebihi 20°, plugin menandakan bacaan sebagai kurang baik dan tidak memberikan isyarat kejayaan.

Pada sumber yang tidak melaporkan tahap ketepatan, plugin meminta gerakan kalibrasi angka lapan. Ia tidak menutup arahan itu hanya kerana telefon dipusing beberapa kali secara mendatar.

Bukti gerakan dianggap mencukupi apabila jumlah putaran heading mencapai sekurang-kurangnya 540°, dan kedua-dua julat beta serta gamma masing-masing berubah sekurang-kurangnya 25°. Gerakan angka lapan sebenar mengubah ketiga-tiga paksi; memusing telefon rata di atas meja tidak.

Itu pun masih bukti tidak langsung, bukan sijil bahawa magnetometer sudah sempurna. Sebab itu pengguna turut diberikan butang pengesahan manual selepas mereka menentukur.

Bagi saya, ini antara prinsip paling penting dalam projek ini: sesuatu sistem yang boleh dipercayai bukan sistem yang sentiasa berkata ia betul. Kadang-kadang sistem yang boleh dipercayai ialah sistem yang tahu bila ia belum cukup pasti.

Mungkin manusia pun patut begitu. Tetapi itu topik lain.

Kalau GPS Gagal, Pengguna Tidak Patut Tersekat

Geolocation hanya bermula selepas pengguna menekan butang. Plugin meminta ketepatan tinggi, memberikan masa sehingga 15 saat dan memberi amaran jika ketepatan yang dilaporkan lebih buruk daripada 500 meter.

Tetapi kebenaran lokasi boleh ditolak. GPS boleh mengambil masa terlalu lama. Desktop pula mungkin tidak mempunyai sensor yang berguna. Saya tidak mahu semua keadaan itu berakhir dengan jalan mati.

Jadi kami membundel pilihan manual sebanyak 532 lokasi: 354 di Malaysia, satu di Singapura, lapan di Brunei dan 169 di Indonesia.

Lokasi manual tidak menyimpan bearing siap kira di dalam dataset. Ia hanya menyimpan koordinat. Apabila pengguna memilih bandar, koordinat itu melalui fungsi bearing yang sama seperti laluan GPS. Hanya ada satu sumber kebenaran untuk matematik.

Dropdown juga bermula kosong. Tiada bandar dipilih secara automatik. Pada alat ibadah, memberi ralat yang jelas lebih selamat daripada memilih lokasi rawak secara senyap lalu memaparkan jawapan dengan penuh keyakinan.

Bagi carian lokasi terdekat, sistem mula-mula menggunakan anggaran equirectangular^[14] yang murah untuk menyusun 532 calon. Hanya calon terbaik kemudian diukur dengan formula geodesik penuh. Ini menjimatkan kerja tanpa mengorbankan keputusan yang diperlukan.

Local-First Dan Privasi

Konsep local-first^[15] bermaksud semua pengiraan berlaku terus di dalam browser pengguna. Koordinat tidak dihantar ke server AkuIslam, tidak disimpan dalam database dan tidak digunakan untuk membina profil lokasi.

Dataset lokasi, formula bearing, formula jarak dan logik kompas semuanya dibundel bersama plugin. Tiada peta luar yang perlu dimuatkan untuk mengetahui ke mana pengguna hendak menghadap.

Saya suka seni bina begini kerana ia menyelesaikan dua perkara serentak: tool lebih pantas dan kita tidak perlu menyimpan data yang sebenarnya kita tidak perlukan.

Prinsip privasi paling mudah ialah ini: kalau sesuatu data tidak perlu sampai kepada kita, jangan minta ia sampai kepada kita.

Kerja Saya Bukan Menulis Semua Kod

Saya banyak mengerah AI untuk projek ini. Claude membuat sebahagian besar kerja implementation dan coding. Saya menyediakan specification, menguji, membaca keputusan, bertanya soalan dan komplen.

Lebih kurang macam client. Bezanya client ini juga tak tahu coding.

ChatGPT pula saya gunakan sebagai second opinion dan juruaudit. Lebih kurang seorang buat kerja, seorang lagi cari salah.

Claude kata A. Saya bawa kepada ChatGPT. ChatGPT jawab, “Hmm…”

Bila AI mula menjawab “Hmm…”, kita tahu petang itu sudah tidak boleh membuat rancangan lain.

Ada audit yang menemui bug sebenar. Ada juga dakwaan yang selepas diperiksa rupanya sudah ditangani oleh kod asal. Itu sebabnya saya tidak mahu satu AI menjadi pelaksana, penguji dan hakim kepada kerjanya sendiri.

Pada satu tahap saya sedar saya sedang menguruskan dua mesin yang jauh lebih pandai coding daripada saya, berbahas tentang kod yang saya sendiri tidak mampu tulis dari kosong, dan saya yang perlu membuat keputusan akhir.

Perfect. Inilah masa depan yang dijanjikan kepada kita. 🤣

Tetapi projek ini mengajar saya bahawa AI tidak menghapuskan keperluan untuk memahami sistem. Ia cuma mengalihkan jenis kerja manusia.

Saya mungkin tidak menulis 3,500 baris JavaScript itu satu per satu, tetapi saya masih perlu memahami apa yang dimaksudkan dengan utara benar, kenapa data orientation relatif perlu ditolak, kenapa 359° dan 1° bukan beza 358°, dan bila tool patut enggan memberikan pengesahan.

Kalau kita sendiri kosong tentang logik benda yang dibina, AI boleh membantu kita menghasilkan kesilapan dengan kelajuan yang sangat mengagumkan.

Sebab itu bahagian terpenting bukan prompt yang berbunyi pandai. Ia ialah specification, pemecahan masalah, ujian edge case, audit bebas dan keberanian untuk bertanya, “Apa andaian yang sedang dibuat oleh sistem ini?”

Keseluruhan plugin akhirnya melalui lebih 900 kes ujian automatik, di samping ujian pada telefon sebenar. Nombor ujian itu bukan jampi yang menjadikan tool sempurna, tetapi ia memberikan cara untuk memastikan pembetulan baharu tidak memecahkan perkara lama.

Complexity Di Belakang, Simplicity Di Depan

Selepas beberapa pusingan development, audit dan berjalan keliling rumah sambil memandang kompas telefon, saya akhirnya membuka tool itu pada iPhone.

Saya benarkan lokasi. Bearing dikira. Sensor mula membaca orientation. Saya pusing telefon. Jarum ikut.

Kemudian apabila telefon menghadap arah kiblat, kompas menjadi hijau. Saya pegang sekejap. Pengesahan muncul.

Saya renung telefon itu.

“Eh.”

“Jadi laaa.”

“Biar betik.” 🤣

Mungkin bagi programmer semua ini biasa sahaja. Bagi saya, ada rasa pelik apabila sesuatu yang beberapa hari sebelumnya cuma wujud sebagai idea dalam kepala sudah menjadi benda sebenar yang boleh digunakan orang.

Di belakangnya ada geolocation, great-circle bearing, WGS84, Lambert, sensor orientation, circular smoothing, hysteresis, kalibrasi dan beratus-ratus keputusan kecil.

Di hadapan pengguna, semuanya patut terasa sangat mudah:

Buka. Benarkan lokasi. Lihat arah kiblat.

Saya suka benda macam itu. Complexity di belakang. Simplicity di depan.

Dan barangkali itulah arah yang saya mahu bawa AkuIslam selepas ini. Bukan meninggalkan artikel dan panduan, tetapi menambah alat-alat kecil yang membantu orang menyelesaikan urusan sebenar.

Hari ini Kompas Arah Kiblat AkuIslam. Selepas ini mungkin waktu solat. Mungkin kiraan lain. Mungkin sesuatu yang saya sendiri belum terfikir.

Saya tulis coretan ini supaya dua tahun lagi saya masih ingat bahawa pada tahun 2026, saya bukan programmer, tetapi saya cuba membina sebuah kompas arah kiblat yang saya sendiri mahu percaya apabila menggunakannya.

Ada dua AI, terlalu banyak tab browser, beberapa kali pecah kepala dan rasa ingin tahu yang terlebih sedikit.

Entah apa lagi saya akan gatal tangan buat selepas ini.