شروع کار با Sceneform

این صفحه مفاهیم کلیدی را با کاوش کد موجود در برنامه نمونه Hello Sceneform توضیح می دهد. توجه داشته باشید:

  • این نمونه از Sceneform و ARCore استفاده می کند.

    برای استفاده از Sceneform بدون ARCore، مراحل زیر را دنبال کنید و در عین حال وابستگی ARCore و الزامات مجوز CAMERA را نادیده بگیرید. همانطور که در Build the Scene توضیح داده شده است، از SceneView در طرح بندی برنامه خود استفاده کنید.

  • این برنامه نمونه به عنوان یک برنامه AR مورد نیاز نوشته شده است.

    برای کسب اطلاعات بیشتر درباره برنامه‌های AR اختیاری در مقابل AR مورد نیاز ، به فعال کردن ARCore مراجعه کنید.

برای شروع با Sceneform در پروژه خود، باید:

  1. افزونه Sceneform را وارد کنید
  2. فایل های build.gradle پروژه خود را پیکربندی کنید
  3. AndroidManifest.xml خود را به روز کنید
  4. بررسی های زمان اجرا را انجام دهید و یک نمای صحنه ایجاد کنید
  5. رندرپذیر ایجاد کنید
  6. صحنه را بسازید

افزونه Sceneform را در پروژه خود وارد کنید

پس از نصب، افزونه Sceneform به شما امکان می دهد دارایی های سه بعدی را در Sceneform SDK برای برنامه های واقعیت افزوده در Android Studio وارد کنید، مشاهده کنید و بسازید. به اندروید استودیو نسخه 3.1 و بالاتر نیاز دارد.

برای نصب افزونه:

  1. در Android Studio تنظیمات Plugins را باز کنید:

    • Windows: File > Settings > Plugins > Browse Repositories

    • macOS: Android Studio > Preferences > Plugins

  2. روی مرور مخازن کلیک کنید و ابزار Google Sceneform Tools (بتا) را نصب کنید.

فایل های build.gradle پروژه خود را پیکربندی کنید

  1. مطمئن شوید که build.gradle پروژه شما دارای مخزن Maven Google است:

    allprojects {
    repositories {
        google()
        …

  2. build.gradle برنامه خود را به‌روزرسانی کنید تا آخرین وابستگی‌های ARCore و Sceneform UX را اضافه کنید و اطمینان حاصل کنید که تنظیمات پروژه شما با هر دو کتابخانه سازگار است.

    android {
    …
    defaultConfig {
        // Sceneform requires minSdkVersion >= 24.
        minSdkVersion 24
        …
    }
    // Sceneform libraries use language constructs from Java 8.
    // Add these compile options if targeting minSdkVersion < 26.
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    …
    // Provides ARCore Session and related resources.
    implementation 'com.google.ar:core:1.15.0'

    // Provides ArFragment, and other UX resources.
    implementation 'com.google.ar.sceneform.ux:sceneform-ux:1.15.0'

    // Alternatively, use ArSceneView without the UX dependency.
    implementation 'com.google.ar.sceneform:core:1.15.0'
}

AndroidManifest.xml خود را به روز کنید

AndroidManifest.xml خود را تغییر دهید تا نشان دهید که برنامه شما از ( AR اختیاری ) یا به ( AR مورد نیاز ) دسترسی ARCore و CAMERA نیاز دارد:

<!-- Both "AR Optional" and "AR Required" apps require CAMERA permission. -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Sceneform requires OpenGL ES 3.0 or later. -->
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

<!-- Indicates that app requires ARCore ("AR Required"). Ensures the app is
     visible only in the Google Play Store on devices that support ARCore.
     For "AR Optional" apps remove this line. -->
<uses-feature android:name="android.hardware.camera.ar" />

<application>
    …
    <!-- Indicates that app requires ARCore ("AR Required"). Causes the Google
         Play Store to download and install Google Play Services for AR along
         with the app. For an "AR Optional" app, specify "optional" instead of
         "required".
    -->
    <meta-data android:name="com.google.ar.core" android:value="required" />
</application>

بررسی های زمان اجرا را انجام دهید و یک نمای صحنه ایجاد کنید

ساده ترین راه برای شروع استفاده از Sceneform و ایجاد نمای صحنه، استفاده از ArFragment است که به طور خودکار مدیریت جلسه ARCore را پس از انجام بررسی های لازم در زمان اجرا ARCore کنترل می کند:

  1. بررسی می‌کند که آیا نسخه سازگار Google Play Services برای AR نصب شده است یا خیر، از کاربر می‌خواهد در صورت لزوم نصب یا به‌روزرسانی کند.

  2. بررسی می‌کند که آیا برنامه به دوربین دسترسی دارد یا خیر، و اگر هنوز به آن اجازه داده نشده است، از کاربر اجازه می‌خواهد

اگر برنامه شما نیاز به درخواست مجوزهای اضافی دارد یا می‌خواهد نحوه و زمان ایجاد جلسه AR را سفارشی کند، در عوض می‌توانید:

  • یک زیر کلاس از ArFragment برای درخواست مجوزهای اضافی ایجاد کنید.

  • از ArSceneView به طور مستقیم استفاده یا گسترش دهید. همانطور که در نمونه منظومه شمسی نشان داده شده است، برنامه شما باید نسخه ARCore را بررسی کرده و setupSession() را برای ایجاد جلسه ARCore به صورت دستی انجام دهد.

پس از عبور چک ها، ArFragment ایجاد می کند:

  1. یک ArSceneView ، قابل دسترسی از طریق getArSceneView() ، که:

    • تصاویر دوربین را از جلسه روی سطح آن رندر می کند

    • یک انیمیشن Sceneform UX داخلی ارائه می کند که به کاربران نشان می دهد چگونه باید تلفن خود را حرکت دهند تا تجربه AR را فعال کنند.

    • Planes شناسایی شده را با استفاده از PlaneRenderer پیش فرض برجسته می کند

  2. یک Session ARCore، قابل دسترسی از طریق getSession()

برای استفاده از ArFragment در برنامه خود، آن را به طرح فعالیت خود اضافه کنید، همانطور که در activity_ux.xml در نمونه Hello Sceneform نشان داده شده است:

<fragment android:name="com.google.ar.sceneform.ux.ArFragment"
    android:id="@+id/ux_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

رندرپذیر ایجاد کنید

Renderable یک مدل سه بعدی است که می تواند در هر نقطه از صحنه قرار گیرد و از مش ها، متریال ها و بافت ها تشکیل شده است.

Renderable ها را می توان از:

برنامه نمونه یک فایل رندرپذیر از یک فایل دارایی 3 بعدی andy.obj ایجاد می کند. وقتی این دارایی وارد می‌شود، افزونه Sceneform build.gradle build.gradle را به‌روزرسانی می‌کند تا افزونه را اعمال کند و یک sceneform.asset() برای مدل وارد شده اضافه کند:

apply plugin: 'com.google.ar.sceneform.plugin'

sceneform.asset('sampledata/models/andy.obj', // 'Source Asset Path' specified during import.
                'default',                    // 'Material Path' specified during import.
                'sampledata/models/andy.sfa', // '.sfa Output Path' specified during import.
                'src/main/res/raw/andy')      // '.sfb Output Path' specified during import.

منبع res/raw/andy برای ایجاد یک ModelRenderable استفاده می شود:

private ModelRenderable andyRenderable;

@Override
protected void onCreate(Bundle savedInstanceState) {
    …

    ModelRenderable.builder()
        .setSource(this, R.raw.andy)
        .build()
        .thenAccept(renderable -> andyRenderable = renderable)
        .exceptionally(
            throwable -> {
            Log.e(TAG, "Unable to load Renderable.", throwable);
            return null;
        });
}

صحنه را بسازید

ARSceneView یک Scene به آن متصل است. صحنه یک ساختار داده درخت مانند است که Node هایی را که اشیاء مجازی هستند نگه می دارد.

در اینجا رندرable andy مستقیماً به root Scene node متصل می شود:

Node node = new Node();
node.setParent(arFragment.getArSceneView().getScene());
node.setRenderable(andyRenderable);

هر گره حاوی تمام اطلاعاتی است که Sceneform برای رندر کردن آن (از جمله موقعیت، جهت، و شیء قابل نمایش آن) و همچنین تعامل با آن (از جمله شکل برخورد و شنوندگان رویداد) نیاز دارد.

گره ها را می توان به گره های دیگر اضافه کرد و یک رابطه والد-فرزند را تشکیل داد. هنگامی که یک گره فرزند یک گره دیگر است، با والد خود حرکت می کند، می چرخد ​​و مقیاس می شود - مانند حرکت بازوهای شما هنگام حرکت بدن شما. یک گره می تواند چندین فرزند داشته باشد، اما فقط یک والد، بنابراین ساختاری درخت مانند را تشکیل می دهد. این ساختار به عنوان نمودار صحنه شناخته می شود.

هر فریم، Sceneform نمودار صحنه را از دید دوربین (با هدایت ردیابی حرکت ARCore) ارائه می‌کند. برنامه شما می‌تواند با گوش دادن به رویدادهای لمسی و اشاره‌ای، انجام تست‌های ضربه در برابر گره‌ها و قرار دادن لنگرها با صحنه تعامل داشته باشد. برای اطلاعات بیشتر، به ساخت و تعامل با صحنه مراجعه کنید.