Paano Gamitin ang Libreng 3D Models Mula Sa Google Poly sa Android Apps

Tagalog (Wikang Tagalog) translation by Robert Alexander (you can also view the original English article)

Mayroong malaking pangangailangan sa mga panahong ito para sa Android apps na nagbibigay ng immersive virtual reality o augmented reality experiences.Bilang developer, mayroong maraming iba’t ibang frameworks na maaari mong gamitin para makagawa ng ganyang apps.

Subalit, maliban na lang kung isa ka ring dalubhasang 3D artist, paano mo gagawin ang 3D objects na ipapakita mo sa apps na iyon?Handa ka na bang maglaan ng ilang buwan na aralin kung paano gawin ang 3D modelling programs katulad ng Blender o Maya? Kung hindi pa, dapat mong isaalang-alang ang paggamit ng Google Poly, isang online repository na naglalaman ng libu-libong 3D assests na may kasamang Creative Commons licenses.

Karamihan sa assets na makikita mo sa Poly ngayon ay low poly na may simpleng materyales. Ito ay dahil ang karaniwang mobile GPU ay hindi pa ganoon kagaling para ipakita ang 3D objects na may mataas na polygon counts sa real time.

Sa pagtuturong ito, ipakikilala ko ang Poly API. Ipapakita ko kung paano gamitin ang Processing para sa Android para i-render ang 3D assets na iyong dinownload.

Unang Kailangan

Para magamit nang husto ang pagtuturong ito, kailangan mo ng:

bagong bersyon ng Android Studio
device na gumagana sa Android API level 21 o mas mataas
at Google Cloud account

1. Pag-acquire ng API Key

Lahat ng HTTP requests na ginagawa mo sa Poly API ay kailangang may kasamang API key na iyong pag-aari. Para ma-acquire ang key, magsimula sa pamamagitan ng pag log-in sa Google Clould console at pag-navigate sa APIs dashboard.

Sunod, pindutin ang Enable APIs at services button, palawigin ang Other category, at piliin ang Poly API.

Other APIs section

Maaari mo ng pindutin ang Enable button para ma-enable ang Poly API.

Kapag na-enable na ang API, awtimatikong nabubuo ang set ng API keys para dito. Maaari mong buksan ang Credentials tab para makita ang mga ito.

Sa pagtuturong ito, kakailanganin mo lang ng Android key. Tandaan ito para magamit ito mamaya.

2. Project Setup

Dahil ang Poly ay walang opisyal na toolkit para sa Android platform sa kasalukuyan, kailangan mong gumawa nang direkta sa Poly gamit ang REST interface nito. Sa pamamagitan ng paggamit ng Fuel networking library, na sadyang para sa Kotlin language,marami kang matitipid na oras at pagod. Kung kaya idagdagdag ang sumusunod na implementation dependency sa build.gradle file ng app module.

1	implementation 'com.github.kittinunf.fuel:fuel-android:1.13.0'

Para maipakita ang 3D assets na iyong dinownload mula sa Poly repository, kailangan mo rin ng rendering engine. Ang pag process para sa Android ay kailangan ito, kaya idagdag ito bilang isa pang dependency.

1	implementation 'org.p5android:processing-core:4.0.1'

Panghuli, huwag kalimutang humingi ng INTERNET permission sa manifest file ng iyong proyekto.

1	<uses-permission android:name="android.permission.INTERNET"/>

3. Paglista ng Assets

Para madownload ang Poly asset, dapat mong alamin ang unique ID nito. Sa pamamagitan ng paggamit ng browser, na nagsu-support ng WebGL, mabilis mong matutukoy ang ID ng kahit na anong asset. Ito ay nasa address bar.

Subalit kung gusto mong payagan ang iyong users na sabay ng run time ay magpasya kung aling assets ang nais nilang gamitin, maaari mong gamitin ang assets.list REST method para matukoy ang IDs ng mga assets na iyon. Sa method na ito ay makakahanap ka ng assets gamit ang iba’t ibang parameters, katulad ng keywords, mga kategorya, at 3D file formats.

Para sa makatutuhanang halimbawa, subukan na nating hanapin ang IDs ng ilang assets na kabilang sa kategorya ng mga hayop. Siyempre, malaya kang makakapili ng kahit na aling iba pang valid na kategorya, katulad ng arkitektura, pagkain, o mga tao.

Bago ka gumawa ng HTTP request, magandang ideya na ideklara ang iyong API key at ang base URL ng Poly API bilang constants sa loob ng iyong aktibidad.

1	companion object {
2	const val key = "Abcdefghabcdefgh1234567810"
3	const val baseURL = "https://poly.googleapis.com/v1"
4	}

Gamit ang baseURL, maaari mong gawin ang URL ng assets.list REST method katulad ng ipinapakita sa ibaba:

1	val listURL = "$baseURL/assets"

Sa puntong ito, maaari ka ng makagawa ng valid na HTTP GET request sa pamamagitan ng pagtawag sa httpGet() method at pagpasa ng iyong API key at ang nais na kategorya bilang query parameters nito. Bilang opsyon, maaari mong gamitin ang format query parameters para matiyak ang nais na format ng assets. Sinu-support ng Poly ang OBJ, TILT, at ilang iba pang sikat na 3D formats.

Dahil ang method ay nagra-run nang wala sa oras at ang resulta ay JSON document, kailangan mong ilagay ang event handler dito sa pamamagitan ng paggamit ng response JSON() method. Ipapakita ng sumusunod na code kung paano:

listURL.httpGet(listOf(
        "category" to "animals",
        "key" to key,
        "format" to "OBJ"
)).responseJson { _, _, result ->

    // More code here
   
}

Sa loob ng event handler, kung matagumpay ang iyong requeset, magkakaroon ka ng access sa listahan ng Asset objects. Ang name field ng bawat nasabing objects ang tumutukoy sa ID nito.

Bilang karagdagan, bawat object ay mayroong fields katulad ng displayName, license, at authorName, na maaaring maging kapaki-pakinabang. Sa ngayon, ilagay lang natin ang name at displayName ng lahat ng objects. Ipapakita ng sumusunod na code kung paano:

result.fold({
    // Get assets array
    val assets = it.obj().getJSONArray("assets")

    // Loop through array
    for(i in 0 until assets.length()) {
        // Get id and displayName
        val id = assets.getJSONObject(i).getString("name")
        val displayName = 
                assets.getJSONObject(i).getString("displayName")

        // Print id and displayName
        Log.d("POLY", "(ID: $id) -- (NAME: $displayName)")
    }
}, {
    // In case of an error
    Log.e("POLY", "An error occurred")
})

Kung ira-run mo ang iyong app ngayon, dapat nakikita mo ang sumusunod na output sa the Logcat window ng Android Studio.

Logcat window showing asset names and IDs

4. Pagda-download ng Assets

Kapag mayroon ka ng unique ID ng asset, maaari mo ng direktang ilagay ito sa base URL ng Poly API para magawa ang asset URL.

// some asset id
val assetID = "assets/3yiIERrKNQr"

// its url
val assetURL = "$baseURL/$assetID"

Kapag gumagawa ka ng HTTP GET request sa asset URL gamit ang the httpGet() method uli, may babalik ng JSON na dokumento na nagtataglay ng isa lang na Asset object.

assetURL.httpGet(listOf("key" to key))
        .responseJson { _, _, result ->
            result.fold({
                val asset = it.obj()
        
                // More code here
        
            }, {
                Log.e("POLY", "An error occurred")
            })
        }

Kung napapansin mo itaas na code, ang request na ito ay dapat mayroon ding query parameter na binabanggit ang iyong API key.

Natutunan mo na kung paano gumamit ng fields na nasa Asset object sa nakaraang hakbang. Ngayon, ay kailangan mo na lang gawin ay gamitin ang formats array na mayroon sa object para malaman ang URLs and pangalan ng files kaugnay ng asset. Bawat item sa array ay magkakaroon ng tatlong importanteng fields:

formatType, kung saan malalaman mo ang uri ng asset
root, na naglalaman ng pangalan at URL ng pangunahing file na may kaugnayan sa asset
resources, na naglalaman ng mga detalye tungkol sa pangalawang files na may kinalaman sa asset, katulad ng materyales at textures

Kapag gumagawa ka sa OBJ format, ang pangunahing file ay .obj file na mayroong vertices at faces data, at ang pangalawang files ay kadalasan .mtl files na mayroong data tungkol ka sa materyales na ginamit. Ipapakita ng sumusunod na code kung paano alamin ang parehong pangunahin at pangalawang files:

var objFileURL:String? = null
var mtlFileURL:String? = null
var mtlFileName:String? = null

val formats = asset.getJSONArray("formats")

// Loop through all formats
for(i in 0 until formats.length()) {
    val currentFormat = formats.getJSONObject(i)

    // Check if current format is OBJ
    if(currentFormat.getString("formatType") == "OBJ") {
        // Get .obj file details
        objFileURL = currentFormat.getJSONObject("root")
                                .getString("url")

        // Get the first .mtl file details
        mtlFileURL = currentFormat.getJSONArray("resources")
                        .getJSONObject(0)
                        .getString("url")

        mtlFileName = currentFormat.getJSONArray("resources")
                        .getJSONObject(0)
                        .getString("relativePath")
        break
    }
}

Sa nasa itaas na code, bilang karagdagan sa URL ng .mtl file, inaalam din natin ang pangalan nito gamit ang relativePath field.Ang paggawa nito ay importante dahil ang pangalan ay hard coded sa mtllib element ng .obj file at hindi dapat baguhin.

Kapag mayroon ka nag URLs ng parehong files, maaari mong gamitin ang httpDownload() method ng Fuel library para i-download ang mga ito. Narito kung paano i-download ang mga ito pribadong storage directory ng iyong app,na ang absolute app ay makikita gamit ang filesDir property:

// download and store obj file as asset.obj
objFileURL!!.httpDownload().destination { _, _ ->
    File(filesDir, "asset.obj")
}.response { _, _, result ->
    result.fold({}, {
        Log.e("POLY", "An error occurred")
    })
}

// download and store mtl file without
// changing its name
mtlFileURL!!.httpDownload().destination { _, _ ->
    File(filesDir, mtlFileName)
}.response { _, _, result ->
    result.fold({}, {
        Log.e("POLY", "An error occurred")
    })
}

5. Pagpakita ng Assets

Kailangan mo ng 3D canvas para makuha mo ang Poly asset na iyong dinownload. Para makagawa nito, kailangan mong palawakin ang PApplet class na handog ng Processing for Android library. Subalit, ang canvass na ginawa sa ganitong paraan, ay dati na, sinu-support lang ang 2D shapes. Para i-configure ito para gumuhit ng hugis 3D din, i-override ang settings() method at ipasa ang P3D bilang argument sa fullScreen() method, kung saan nagagawa din nitong gawing malaki ang canvas kasing laki ng screen ng user.

val canvas = object : PApplet() {
    override fun settings() {
        fullScreen(PConstants.P3D)
    }

    // More code here
}

Sunod, gumawa ng bagong property sa loob ng class para kumatawan sa Poly asset bilang PShape object.

1	var myPolyAsset: PShape? = null

Para simulan ang property, i-override ang setup() method at i-call ang loadShape() method, na pinapasa ang absolute path ng .obj file na iyong dinownload bilang argument nito.

1	override fun setup() {
2	myPolyAsset = loadShape(File(filesDir, "asset.obj").absolutePath)
3	}

Maaari mo ng simulang gumuhit sa canvass sa pamamagitan ng pag override ng draw() method. Sa loob ng method, ang unang bagay na kailangan mong gawin ay i-call ang background() method para masigurado na lagi kang gumuguhit sa blankong canvas.

override fun draw() {
    background(0)
        
    // More code here
}

Kapag ginuhit nang direkta, karamihan sa Poly assets ay mukhang napakaliit at baliktad. Maaari mo itong ayusin sa pamamagitan ng alinman sa paggamit ng custom camera o sa pamamagitan ng paggamit ng canvas transformations.Para mapanatiling simple at madaling maintindihan ang pagtuturong ito, gamitin natin ang canvas transformations.

Para lumaki ang sukat ng asset, gamitin ang scale() method at ipasa ang malaking negative value dito. Ang value ay dapat negative para masigurado na ang asset ay mapataob ng patayo. Bilang opsyon, maaari mong gamitin ang translate () method para mabago ang posisyon nito sa gawing X and Y axes. Ang sumusunod na code ay ipapakita kung papaano:

1	scale(-50f)
2	translate(-4f,-14f)

Maaari mo ng ituloy at iguhit ang asset sa pamamagitan ng pag call ng shape() method.

1	shape(myPolyAsset)

Ang canvas sa kasalukuyan ay hindi parte ng view hierarchy ng iyong aktibidad. Kung kaya, kung sinusubukan mong i-run ang iyong app ngayon, hindi mo makikita ang asset. Para maayos ito, una ilagay ang bagong FrameLayout widget sa layout XML file ng aktibidad.

<FrameLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/canvas_holder">
</FrameLayout>

Pagkatapos, gumawa ng bagong PFragment instance gamit ang canvas at ituro ito sa FrameLayout widget.

1	val fragment = PFragment(canvas)
2	fragment.setView(canvas_holder, this)

Sa puntong ito, maaari mong i-run ang app uli para makita ang asset.

Konklusyon

Alam mo na kung paano gamitin ang Poly API para hanapin at i-download ang 3D assets. Sa pagtuturong ito, natutunan mo rin kung paano mag render at imanipula ang mga assets na iyon gamit ang Processing para sa Android.

Mahalagang alalahanin na marami sa mga assets na mayroon sa Poly ay ginawa gamit ang Google Blocks, isang application para sa users ng HTC Vive at Oculus Rift.Kapag mayroon kang VR headsets na iyon, isaalang-alang ang paggawa at pagpadala ng iyong sariling models.

Para mas matutunan pa ang tungkol sa Poly API, maaari mo itong isangguni sa opisyal na dokumentasyon.