引入

环境准备

1. 鉴权和认证 要使用Phoenix SDK，您需要拥有一个百度智能云账号和一个有效的 AK(Access Key ID)、SK(Secret Access Key)用来进行签名认证。

   可以通过如下步骤获得并了解您的AK/SK信息：

   1. 注册百度智能云账号
   2. 创建AK/SK
2. 从此处下载 Phoenix-{verison}.aar。（version为具体版本号）

引入方法

1. 将Phoenix-{verison}.aar 引入到工程里，如：

   implementation fileTree(dir: "aar", include: ["Phoenix-2.1.1.0.aar"])

   混淆规则已经内置于aar内，无需手动配置。

2. 引入sdk所需依赖：gson，okhttp

    implementation 'com.google.code.gson:gson:2.8.6'
    implementation 'com.squareup.okhttp3:okhttp:4.7.2'

具体功能

全景：全景图渲染，相机操作，多种交互模式，热点等

环物：环物渲染，手势操作，多种交互模式，热点等

快速入门

本节介绍如何快速使用Phoenix SDK完成常见操作。具体接口以及参数定义详细参考API章节。

初始化

Phoenix SDK 使用前需要进行初始化，传入申请的 ak sk，依据回调结果进行后续操作。

1. 鉴权通过 onAuthSuccess()，Phoenix SDK 可以正常使用配置的功能权限。
2. 鉴权失败 onAuthFailed()， 一般是ak sk 错误。

PhoenixSDK.getInstance().authorize("ak",
                "sk", new PhoenixSDK.OnAuthorizeListener() {
                    @Override
                    public void onAuthSuccess() {
                        
                    }

                    @Override
                    public void onAuthFailed() {
                        
                    }
                });

创建view

全景view：PanoView 环物view：SpinView

上述两个view可以直接写在xml，也可以动态添加，以xml中 PanoView为例

    <com.baidu.vr.phoenix.pano.PanoView
        android:id="@+id/pano_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

在对应的Activity里，对PanoView操作即可。

全景

1. 渲染全景图片

目前全景图支持四种渲染类型，分别是 cube 散图、cube 雪碧图、单张全景图和分级分块图。

首先创建 PanoConfiguration:

PanoConfiguration config = new PanoConfiguration(resourceString);

同时，PanoConfiguration 还有参数：

• enterAnimationType（入场动画，默认无）
• tileUpdateDuration （瓦片加载延迟 ，默认500ms）

参数可以通过set接口进行设置。而后调用 init (PanoConfiguration configration) 初始化场景。

2. 增加热点

首先建造出 SpinHotSpot，如：

        Hotspot hotspot = HotspotBuilder.create()
                .provider(v)
                .position(-3.14f, 6.86f, -30.28f)// 归一化坐标
                .build();

而后调用：addHotspot(Hotspot hotspot) 增加热点

3. 属性动画

属性动画可以对场景内的 camera 进行动画操作，

可操作的属性如下：eyeX eyeY eyeZ pitch yaw roll lookX lookY lookZ

调用方式举例：

PropertyValuesHolder pitch =
                PropertyValuesHolder.ofFloat("pitch", panoView.getCamera(), 0f);
PropertyValuesHolder yaw =
                PropertyValuesHolder.ofFloat("yaw", panoView.getCamera(), 0f);
PropertyValuesHolder roll =
                PropertyValuesHolder.ofFloat("roll", panoView.getCamera(), 0f);
ObjectAnimator animator = ObjectAnimator.ofPropertyValuesHolder(eyeZ, pitch, yaw, roll)
                .setDuration(2000);
panoView.startAnimation(animator)

环物

1. 渲染环物

首先创建SpinConfiguration:

SpinConfiguration spinConfig = new SpinConfiguration(resourceString);

同时SpinConfiguration 还有参数：

• initRow （初始化 row 视角，默认 0 ）
• initCol（初始化 col 视角， 默认 0 ）
• enterAnimationType （入场动画，默认无）
• tileUpdateDuration （瓦片加载延迟，默认500ms）

参数可以通过set接口设置。而后调用init (SpinConfiguration configuration)初始化场景。

2. 热点

首先建造出SpinHotSpot，如：

SpinHotspot spinHotspot = new SpinHotspotBuilder()
        .provider(v)
        .position(x, y) // 归一化坐标
        .build();

而后调用：addHotspot(SpinHotspot hotspot) 增加热点

3. 属性动画

属性动画目前三个：currentCol currentRow currentScale

调用方式举例：

ObjectAnimator animator = ObjectAnimator.ofInt(spinView, "currentCol",0, 12);
spinview.startAnimation(animator)

API及参数

全景

API列表

场景配置相关接口

1. void init(PanoConfiguration configuration) 初始化场景

参数：PanoConfiguration

资源 json 字符串样例，具体参见 demo：

{
    "resource_type": "pano",
    "render_type": "cube-multi",
    "resource": {
        "file": "panos/input.tiles/%s/l%l/%v/l%l_%s_%v_%h.jpg",
        "url": "https://bj.bcebos.com/v1/repos3d/penglai/pano_packages/pack_pano_default_07/pieces/panos/input.tiles/",
        "tileSize": [
            512,
            1152,
            2304,
            4608
        ]
    }
}

使用方法：

PanoConfiguration config = new PanoConfiguration(resourceStr);
config.setTileUpdateDuration(10);
panoView.init(config);

2. void switchView(PanoConfiguration newConfiguration) 切换场景

切换场景会清除当前场景的视角，热点。

参数：PanoConfiguration

使用方法：

PanoConfiguration config = new PanoConfiguration(resourceStr);
config.setTileUpdateDuration(10);
panoView.switchView(config);

3. void updateConfiguration(PanoConfiguration newConfiguration) 更新场景配置

更新配置会保留当前场景的视角，热点。

参数：PanoConfiguration

使用方法：

PanoConfiguration config = new PanoConfiguration(resourceStr);
config.setTileUpdateDuration(10);
panoView.updateConfiguration(config);

交互相关接口

1. void panEnabled(boolean enable) 手指拖动开关

默认值：开启，通过此接口来开关手指拖动操作

2. boolean isPanEnabled() 手指拖动操作是否开启

使用此接口来判断手指拖动操作是否开启

3. void sensorEnabled(boolean enable) 陀螺仪开关

默认值：关闭，通过此接口来开关陀螺仪

4. boolean isSensorEnabled() 陀螺仪是否开启

使用此接口来判断陀螺仪是否开启

5. void pinchEnabled(boolean enable) pinch 操作开关

默认值：开启，通过此接口来开关 pinch 操作

6. boolean isPinchEnabled() pinch 操作是否开启

使用此接口来判断 pinch 操作是否开启

7. void pitchEnabled(boolean enable) pitch 操作开关

默认值：开启，通过此接口来开关 pitch 操作

8. boolean isPitchEnabled() pitch 操作是否开启

使用此接口来判断 pitch 操作是否开启

热点相关接口

1. void addHotspot(Hotspot hotspot) 增加热点

使用方法：首先建造出 HotSpot，如：

View view = LayoutInflater.from(getBaseContext()).inflate(R.layout.hotspot_view, null);        
Hotspot hotspot = HotspotBuilder.create()
                .provider(view)
                .position(x, y, z)// 归一化坐标
                .build();

其中，HotspotBuilder 是 Hotspot 的建造者，传入自定义的热点 view， 以及热点所处的位置坐标(x, y , z)，即可创建出热点 hotspot

而后调用该接口增加热点即可。

2. void removeHotspot(Hotspot hotspot) 删除热点

使用该接口从场景中删除传入的热点

3. void removeAllHotspots() 删除所有热点

使用该接口删除场景中所有的热点

摄像机相关接口

1. Camera getCamera() 获取场景的 camera

   获取 camera 之后，可以对 camera 做如下操作，也可以利用 camera 做属性动画。

   方法	描述
   void setFov(float fov)	设置 Fov
   float getFov()	获取 Fov
   void setMinFov(float minFov)	设置 minFov
   float getMinFov()	获取 minFov
   void setMaxFov(float maxFov)	设置 maxFov
   float getMaxFov()	获取 maxFov
   void setPitchRange(float min, float max)	设置 pitch范围（0-90）
   float getMinPitch()	获取 minPitch
   float getMaxPitch()	获取 maxPitch
   void setEyeX(float eyeX)	设置 eyeX
   float getEyeX()	获取 eyeX
   void setEyeY(float eyeY)	设置 eyeY
   float getEyeY()	获取 eyeY
   void setEyeZ(float eyeZ)	设置 eyeZ
   float getEyeZ()	获取 eyeZ
   void setLookX(float lookX)	设置 lookX
   float getLookX()	获取 lookX
   void setLookY(float lookY)	设置 lookY
   float getLookY()	获取 lookY
   void setRoll(float roll)	设置 roll
   float getRoll()	获取 roll
   void setYaw(float yaw)	设置 yaw
   float getYaw()	获取 yaw
   void setPitch(float pitch)	设置 pitch
   float getPitch()	获取 pitch

动画相关接口

1. void startAnimation(Animator animator) 开始一个属性动画

属性动画可以对场景内的 camera 进行动画操作，

可操作的属性如下：eyeX eyeY eyeZ pitch yaw roll lookX lookY lookZ

调用方式举例：

PropertyValuesHolder pitch =
                PropertyValuesHolder.ofFloat("pitch", panoView.getCamera(), 0f);
PropertyValuesHolder yaw =
                PropertyValuesHolder.ofFloat("yaw", panoView.getCamera(), 0f);
PropertyValuesHolder roll =
                PropertyValuesHolder.ofFloat("roll", panoView.getCamera(), 0f);
ObjectAnimator animator = ObjectAnimator.ofPropertyValuesHolder(eyeZ, pitch, yaw, roll)
                .setDuration(2000);
panoView.startAnimation(animator)

2. void stopAnimation(Animator animator) 停止一个属性动画

使用该接口可以停止自定义的属性动画

快照相关接口

1. void setOnSnapshotListener(VRLibrary.OnSnapshotListener listener) 设置快照侦听

在获取快照接口之前，必须设置快照侦听，通过侦听回调获取的快照 bitmap

2. void requestSnapshot() 获取快照

获取快照接口，调用之后，通过设置的快照侦听回调获取的快照。

回调接口

1. void setOnLoadListener(OnLoadListener listener) 设置场景加载侦听

场景加载过程，通过该侦听回调各个阶段：

    public interface OnLoadListener {
        void onLoadStart();
        void onLoadFinish(int errorCode, String errorMsg);
        void onLoadTileFailed(String errorMsg);
    }

2. void addGestureListener(VRLibrary.IGestureListener listener) 设置手势侦听

手势会通过该侦听回调各个手势操作：

    interface IGestureListener {
        void onClick(MotionEvent e);
        void onDrag();
        void onFling();
        void onPinch();
    }

3. void removeGestureListener(VRLibrary.IGestureListener listener) 移除手势侦听

通过该接口可以移除设置的手势侦听

4. void setPanoTouchListener(OnPanoTouchListener panoTouchListener) 设置onTouch侦听

通过该接口可以设置 Touch 侦听， 可以实现自动巡游的触碰停止等。如：

        panoView.setPanoTouchListener(new PanoView.OnPanoTouchListener() {
            @Override
            public void onTouch(View view, MotionEvent motionEvent) {
                panoView.stopAnimation(animator);
            }
        });

环物

API列表

场景配置相关接口

1. void init(SpinConfiguration configuration) 初始化场景

参数：SpinConfiguration

资源 json 字符串样例，具体参见 demo：

{
    "resource_type": "spin",
    "render_type": "multi-tile",
    "resource": {
        "tilePath": "https://repos3d.cdn.bcebos.com/penglai/materials/ma_90f839f86/pieces/origin/spin_720_scene2",
        "coverImage": "${row}_${col}_cover.jpg",
        "extension": "jpg",
        "tileFile": "${row}_${col}_files",
        "tileSize": 510,
        "width": 3000,
        "height": 2000,
				"minLevel": 10,
        "colCount": 36,
        "rowCount": 2,
        "coverWidth": 512,
        "coverHeight": 314
    }
}

使用方法：

SpinConfiguration spinConfig = new SpinConfiguration(resourceStr);
spinConfig.setInitRow(1);
spinConfig.setInitCol(0);
spinConfig.setEnterAnimationType(SpinView.EnterAnimationType.spinOnly);
spinConfig.setTileUpdateDuration(10);
spinView.init(spinConfig);

2. void updateConfiguration(PanoConfiguration newConfiguration) 更新配置

参数：SpinConfiguration

更新配置会保留场景内热点、缩放平移等信息，可用做替换外观颜色等需求

使用方法：

pinConfiguration spinConfig = new SpinConfiguration(resourceStr);
spinConfig.setInitRow(spinView.getCurrentRow());
spinConfig.setInitCol(spinView.getCurrentCol());
spinView.updateConfiguration(spinConfig);

交互相关接口

1. void spinRound(boolean reverse, int intervalTime) 旋转一圈

使用该接口可以旋转一周。参数如下：

reverse ： 是否反方向旋转

intervalTime： 旋转切换视角间隔

2. void spinTo(int targetRow, int targetCol) 转至 targetRow targetCol

使用该接口可以切换至目标行，目标列。参数如下：

targetRow ： 目标 Row

targetCol： 目标 Col

3. void spinBy(int deltaRow, int deltaCol) 转动 deltaRow deltaCol

使用该接口可以转动 deltaRow行，deltaCol列。参数如下：

deltaRow ： 转动 Row 的增量

deltaCol： 转动 Col 的增量

4. void zoom(float scale) 缩放

使用该接口可以进行缩放。

5. void panTo(float x, float y) 平移

使用该接口可以在放大状态下，进行平移。参数如下：

x ：目标中心点 x 坐标

y ：目标中心点 y 坐标

6. void panToCenter() 平移至中心

使用该接口可以在放大状态下，以图片中心点为视口中心点进行平移。

7. void setHorizontalReversal(boolean reversal) 反转水平方向开关

使用该接口可以设置水平方向反转，当设置为 true 时， 使得手势拖动旋转时，水平旋转方向反转。

8. boolean getHorizontalReversal() 水平方向是否反转

使用该接口可以获取水平方向是否反转。

9. void setVerticalReversal(boolean reversal) 反转竖直方向开关

使用该接口可以设置竖直方向反转，当设置为 true 时， 使得手势拖动旋转时，竖直旋转方向反转。

10. boolean getVerticalReversal() 竖直方向是否反转

使用该接口可以获取水平方向是否反转。

11. void enableSpin(boolean enable) spin操作开关

默认值：关闭，通过此接口来开关放大状态下手指拖动时，是否切换视角。

12. boolean isSpinEnabled() spin操作是否开启

使用该接口可以获取 spin 操作是否开启

13. void enablePan(boolean enable) pan操作开关

默认值：开启，通过此接口来开关放大状态下手指拖动时，是否平移。

pan 操作 和 spin 操作互斥，也就是说开启一个，另一个自动关闭。

14. boolean isPanEnabled() pan操作是否开启

使用该接口可以获取 pan 操作是否开启

15. void enableGestureZoom(boolean enable) 手势缩放开关

默认值：开启，通过此接口来开关是否允许手势缩放。

16. boolean isGestureZoomEnabled() 手势缩放是否开启

使用该接口可以获取手势缩放操作是否开启

热点相关接口

1. void addHotspot(SpinHotspot hotspot) 增加热点

   使用方法：首先建造出 SpinHotSpot，如：

View view = LayoutInflater.from(getBaseContext()).inflate(R.layout.hotspot_view, null);        
Hotspot hotspot = SpinHotspotBuilder.create()
                .provider(view)
                .attach(spinView.getCurrentRow(), spinView.getCurrentCol())
                .position(0.5f, 0.2f)
                .build();

其中，SpinHotspotBuilder 是 SpinHotSpot 的建造者，传入自定义的热点 view，热点所依附的 row col 以及热点所处的位置坐标(x, y)，即可创建出热点 hotspot。

而后调用该接口增加热点即可。

2. void removeHotspot(SpinHotspot hotspot) 删除热点 使用该接口从场景中删除传入的热点

3. void removeAllHotspots() 删除所有热点

   使用该接口删除场景中所有的热点

动画相关接口

1. void startAnimation(Animator animator) 开始一个属性动画

属性动画目前可以操作的属性有三个：currentCol currentRow currentScale

调用方式举例：

ObjectAnimator animator = ObjectAnimator.ofInt(spinView, "currentCol",0, 12);
spinview.startAnimation(animator)

2. void stopAnimation(Animator animator) 停止一个属性动画

使用该接口可以停止自定义的属性动画

回调接口

1. void setOnLoadListener(OnLoadListener listener) 设置加载侦听

场景加载过程，通过该侦听回调各个阶段：

    public interface OnLoadListener {
        void onLoadStart();
        void onLoadCoverFinish();
        void onLoadFinish(int errorCode, String errorMsg);
        void onLoadTileFailed(String errorMsg);
    }

2. void setOnSpinRoundListener(OnSpinRoundListener listener) 设置旋转侦听

旋转过程中的回调：

    public interface OnSpinRoundListener {
        void onRoundStart();
        void onRoundFinish();
    }

3. void setOnScaleChangeListener(OnScaleChange listener) 设置缩放倍数改变侦听

缩放过程中，缩放系数通过该侦听回调：

    public interface OnScaleChange {
        void onChange(float scale);
    }

4. void setSpinTouchListener(OnSpinTouchListener mTouchListener) 设置 touch 侦听

通过该接口可以设置 Touch 侦听， 可以实现自动巡游的触碰停止等。如：

spinView.setSpinTouchListener(new SpinView.OnSpinTouchListener() {
            @Override
            public void onTouch(View view, MotionEvent motionEvent) {
                spinView.stopAnimation(animator1);
            }
        });

其它接口

1. void setMinimumScale(float minScale) 设置最小缩放倍数

   通过此接口设置最小缩放倍数

2. float getMinimumScale() 获取最小缩放倍数

   通过此接口获取最小缩放倍数

3. void setMaximumScale(float maxScale) 设置最大缩放倍数

   通过此接口设置最大缩放倍数

4. float getMaximumScale() 获取最大缩放倍数

   通过此接口获取最大缩放倍数

5. float getCurrentScale() 获取当前缩放倍数

   通过此接口获取当前缩放倍数

6. void setCurrentCol(int currentCol) 设置 currentCol

   通过此接口设置当前Col

7. int getCurrentCol() 获取 currentCol

   通过此接口获取当前Col

8. void setCurrentRow(int currentRow) 设置 currentRow

   通过此接口设置当前Row

9. int getCurrentRow() 获取 currentRow

   通过此接口获取当前Row

10. void reset() 重置缩放、平移

    通过此接口重置当前角度图片的缩放、平移。

完整创建流程见demo

功能发布记录

版本v1.0.0（2021-10）

首次发布：

支持创建、展示、动画、手势交互等功能