From 879cb8f1a8b0d0a2b15259cebafba3f9051bacbd Mon Sep 17 00:00:00 2001
From: Terry Jia <terryjia88@gmail.com>
Date: Tue, 11 Nov 2025 04:02:12 -0500
Subject: [PATCH] support panoramic image in 3d node (#6638)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Adds panoramic image support to the 3D node viewer, allowing users to
display equirectangular panoramic images as immersive backgrounds
alongside the existing tiled image mode.

## Changes

- Toggle between tiled and panorama rendering modes for background
images
- Field of view (FOV) control for panorama mode
- Refactored FOV slider into reusable PopupSlider component

## Screenshots


https://github.com/user-attachments/assets/8955d74b-b0e6-4b26-83ca-ccf902b43aa6

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-6638-support-panoramic-image-in-3d-node-2a56d73d365081b98647f988130e312e)
by [Unito](https://www.unito.io)
---
 src/components/load3d/Load3DControls.vue      |   2 +
 src/components/load3d/Load3dViewerContent.vue |   2 +
 .../load3d/controls/CameraControls.vue        |  51 ++------
 .../load3d/controls/PopupSlider.vue           |  64 ++++++++++
 .../load3d/controls/SceneControls.vue         |  35 ++++++
 .../controls/viewer/ViewerSceneControls.vue   |  25 ++++
 src/composables/useLoad3d.ts                  |  21 +++-
 src/composables/useLoad3dViewer.ts            |  31 ++++-
 .../core/load3d/Load3DConfiguration.ts        |   6 +-
 src/extensions/core/load3d/Load3d.ts          |   5 +
 src/extensions/core/load3d/SceneManager.ts    | 110 +++++++++++++-----
 src/extensions/core/load3d/interfaces.ts      |   3 +
 src/locales/en/main.json                      |   5 +-
 tests-ui/tests/composables/useLoad3d.test.ts  |  30 ++++-
 .../tests/composables/useLoad3dViewer.test.ts |   4 +-
 15 files changed, 310 insertions(+), 84 deletions(-)
 create mode 100644 src/components/load3d/controls/PopupSlider.vue

diff --git a/src/components/load3d/Load3DControls.vue b/src/components/load3d/Load3DControls.vue
index d8e977fce..d587d79d8 100644
--- a/src/components/load3d/Load3DControls.vue
+++ b/src/components/load3d/Load3DControls.vue
@@ -39,6 +39,8 @@
         v-model:show-grid="sceneConfig!.showGrid"
         v-model:background-color="sceneConfig!.backgroundColor"
         v-model:background-image="sceneConfig!.backgroundImage"
+        v-model:background-render-mode="sceneConfig!.backgroundRenderMode"
+        v-model:fov="cameraConfig!.fov"
         @update-background-image="handleBackgroundImageUpdate"
       />
 
diff --git a/src/components/load3d/Load3dViewerContent.vue b/src/components/load3d/Load3dViewerContent.vue
index fc7ef6869..b42c22330 100644
--- a/src/components/load3d/Load3dViewerContent.vue
+++ b/src/components/load3d/Load3dViewerContent.vue
@@ -34,6 +34,8 @@
             <SceneControls
               v-model:background-color="viewer.backgroundColor.value"
               v-model:show-grid="viewer.showGrid.value"
+              v-model:background-render-mode="viewer.backgroundRenderMode.value"
+              v-model:fov="viewer.fov.value"
               :has-background-image="viewer.hasBackgroundImage.value"
               @update-background-image="viewer.handleBackgroundImageUpdate"
             />
diff --git a/src/components/load3d/controls/CameraControls.vue b/src/components/load3d/controls/CameraControls.vue
index 66e00cb48..fb2d153b7 100644
--- a/src/components/load3d/controls/CameraControls.vue
+++ b/src/components/load3d/controls/CameraControls.vue
@@ -6,65 +6,30 @@
           value: $t('load3d.switchCamera'),
           showDelay: 300
         }"
-        :class="['pi', getCameraIcon, 'text-lg text-white']"
+        :class="['pi', 'pi-camera', 'text-lg text-white']"
       />
     </Button>
-    <div v-if="showFOVButton" class="show-fov relative">
-      <Button class="p-button-rounded p-button-text" @click="toggleFOV">
-        <i
-          v-tooltip.right="{ value: $t('load3d.fov'), showDelay: 300 }"
-          class="pi pi-expand text-lg text-white"
-        />
-      </Button>
-      <div
-        v-show="showFOV"
-        class="absolute top-0 left-12 rounded-lg bg-black/50 p-4 shadow-lg"
-        style="width: 150px"
-      >
-        <Slider v-model="fov" class="w-full" :min="10" :max="150" :step="1" />
-      </div>
-    </div>
+    <PopupSlider
+      v-if="showFOVButton"
+      v-model="fov"
+      :tooltip-text="$t('load3d.fov')"
+    />
   </div>
 </template>
 
 <script setup lang="ts">
 import Button from 'primevue/button'
-import Slider from 'primevue/slider'
-import { computed, onMounted, onUnmounted, ref } from 'vue'
+import { computed } from 'vue'
 
+import PopupSlider from '@/components/load3d/controls/PopupSlider.vue'
 import type { CameraType } from '@/extensions/core/load3d/interfaces'
 
-const showFOV = ref(false)
-
 const cameraType = defineModel<CameraType>('cameraType')
 const fov = defineModel<number>('fov')
 const showFOVButton = computed(() => cameraType.value === 'perspective')
-const getCameraIcon = computed(() => {
-  return cameraType.value === 'perspective' ? 'pi-camera' : 'pi-camera'
-})
-
-const toggleFOV = () => {
-  showFOV.value = !showFOV.value
-}
 
 const switchCamera = () => {
   cameraType.value =
     cameraType.value === 'perspective' ? 'orthographic' : 'perspective'
 }
-
-const closeCameraSlider = (e: MouseEvent) => {
-  const target = e.target as HTMLElement
-
-  if (!target.closest('.show-fov')) {
-    showFOV.value = false
-  }
-}
-
-onMounted(() => {
-  document.addEventListener('click', closeCameraSlider)
-})
-
-onUnmounted(() => {
-  document.removeEventListener('click', closeCameraSlider)
-})
 </script>
diff --git a/src/components/load3d/controls/PopupSlider.vue b/src/components/load3d/controls/PopupSlider.vue
new file mode 100644
index 000000000..0d93e20b9
--- /dev/null
+++ b/src/components/load3d/controls/PopupSlider.vue
@@ -0,0 +1,64 @@
+<template>
+  <div class="relative show-slider">
+    <Button class="p-button-rounded p-button-text" @click="toggleSlider">
+      <i
+        v-tooltip.right="{ value: tooltipText, showDelay: 300 }"
+        :class="['pi', icon, 'text-lg text-white']"
+      />
+    </Button>
+    <div
+      v-show="showSlider"
+      class="absolute top-0 left-12 rounded-lg bg-black/50 p-4 shadow-lg w-[150px]"
+    >
+      <Slider
+        v-model="value"
+        class="w-full"
+        :min="min"
+        :max="max"
+        :step="step"
+      />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import Button from 'primevue/button'
+import Slider from 'primevue/slider'
+import { onMounted, onUnmounted, ref } from 'vue'
+
+const {
+  icon = 'pi-expand',
+  min = 10,
+  max = 150,
+  step = 1
+} = defineProps<{
+  icon?: string
+  tooltipText: string
+  min?: number
+  max?: number
+  step?: number
+}>()
+
+const value = defineModel<number>()
+const showSlider = ref(false)
+
+const toggleSlider = () => {
+  showSlider.value = !showSlider.value
+}
+
+const closeSlider = (e: MouseEvent) => {
+  const target = e.target as HTMLElement
+
+  if (!target.closest('.show-slider')) {
+    showSlider.value = false
+  }
+}
+
+onMounted(() => {
+  document.addEventListener('click', closeSlider)
+})
+
+onUnmounted(() => {
+  document.removeEventListener('click', closeSlider)
+})
+</script>
diff --git a/src/components/load3d/controls/SceneControls.vue b/src/components/load3d/controls/SceneControls.vue
index b0fa98f21..62c57efb8 100644
--- a/src/components/load3d/controls/SceneControls.vue
+++ b/src/components/load3d/controls/SceneControls.vue
@@ -51,6 +51,28 @@
       </Button>
     </div>
 
+    <div v-if="hasBackgroundImage">
+      <Button
+        class="p-button-rounded p-button-text"
+        :class="{ 'p-button-outlined': backgroundRenderMode === 'panorama' }"
+        @click="toggleBackgroundRenderMode"
+      >
+        <i
+          v-tooltip.right="{
+            value: $t('load3d.panoramaMode'),
+            showDelay: 300
+          }"
+          class="pi pi-globe text-lg text-white"
+        />
+      </Button>
+    </div>
+
+    <PopupSlider
+      v-if="hasBackgroundImage && backgroundRenderMode === 'panorama'"
+      v-model="fov"
+      :tooltip-text="$t('load3d.fov')"
+    />
+
     <div v-if="hasBackgroundImage">
       <Button
         class="p-button-rounded p-button-text"
@@ -72,6 +94,9 @@
 import Button from 'primevue/button'
 import { computed, ref } from 'vue'
 
+import PopupSlider from '@/components/load3d/controls/PopupSlider.vue'
+import type { BackgroundRenderModeType } from '@/extensions/core/load3d/interfaces'
+
 const emit = defineEmits<{
   (e: 'updateBackgroundImage', file: File | null): void
 }>()
@@ -79,6 +104,11 @@ const emit = defineEmits<{
 const showGrid = defineModel<boolean>('showGrid')
 const backgroundColor = defineModel<string>('backgroundColor')
 const backgroundImage = defineModel<string>('backgroundImage')
+const backgroundRenderMode = defineModel<BackgroundRenderModeType>(
+  'backgroundRenderMode',
+  { default: 'tiled' }
+)
+const fov = defineModel<number>('fov')
 const hasBackgroundImage = computed(
   () => backgroundImage.value && backgroundImage.value !== ''
 )
@@ -113,4 +143,9 @@ const uploadBackgroundImage = (event: Event) => {
 const removeBackgroundImage = () => {
   emit('updateBackgroundImage', null)
 }
+
+const toggleBackgroundRenderMode = () => {
+  backgroundRenderMode.value =
+    backgroundRenderMode.value === 'panorama' ? 'tiled' : 'panorama'
+}
 </script>
diff --git a/src/components/load3d/controls/viewer/ViewerSceneControls.vue b/src/components/load3d/controls/viewer/ViewerSceneControls.vue
index 0e374ff91..3648b0256 100644
--- a/src/components/load3d/controls/viewer/ViewerSceneControls.vue
+++ b/src/components/load3d/controls/viewer/ViewerSceneControls.vue
@@ -32,6 +32,24 @@
     </div>
 
     <div v-if="hasBackgroundImage" class="space-y-2">
+      <div class="flex gap-2">
+        <Button
+          :severity="backgroundRenderMode === 'tiled' ? 'primary' : 'secondary'"
+          :label="$t('load3d.tiledMode')"
+          icon="pi pi-th-large"
+          class="flex-1"
+          @click="setBackgroundRenderMode('tiled')"
+        />
+        <Button
+          :severity="
+            backgroundRenderMode === 'panorama' ? 'primary' : 'secondary'
+          "
+          :label="$t('load3d.panoramaMode')"
+          icon="pi pi-globe"
+          class="flex-1"
+          @click="setBackgroundRenderMode('panorama')"
+        />
+      </div>
       <Button
         severity="secondary"
         :label="$t('load3d.removeBackgroundImage')"
@@ -50,6 +68,9 @@ import { ref } from 'vue'
 
 const backgroundColor = defineModel<string>('backgroundColor')
 const showGrid = defineModel<boolean>('showGrid')
+const backgroundRenderMode = defineModel<'tiled' | 'panorama'>(
+  'backgroundRenderMode'
+)
 
 defineProps<{
   hasBackgroundImage?: boolean
@@ -77,4 +98,8 @@ const handleImageUpload = (event: Event) => {
 const removeBackgroundImage = () => {
   emit('updateBackgroundImage', null)
 }
+
+const setBackgroundRenderMode = (mode: 'tiled' | 'panorama') => {
+  backgroundRenderMode.value = mode
+}
 </script>
diff --git a/src/composables/useLoad3d.ts b/src/composables/useLoad3d.ts
index bbcebbde6..30cfd0cf1 100644
--- a/src/composables/useLoad3d.ts
+++ b/src/composables/useLoad3d.ts
@@ -31,7 +31,8 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
   const sceneConfig = ref<SceneConfig>({
     showGrid: true,
     backgroundColor: '#000000',
-    backgroundImage: ''
+    backgroundImage: '',
+    backgroundRenderMode: 'tiled'
   })
 
   const modelConfig = ref<ModelConfig>({
@@ -131,7 +132,11 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
     // Restore configs - watchers will handle applying them to the Three.js scene
     const savedSceneConfig = node.properties['Scene Config'] as SceneConfig
     if (savedSceneConfig) {
-      sceneConfig.value = savedSceneConfig
+      sceneConfig.value = {
+        ...sceneConfig.value,
+        ...savedSceneConfig,
+        backgroundRenderMode: savedSceneConfig.backgroundRenderMode || 'tiled'
+      }
     }
 
     const savedModelConfig = node.properties['Model Config'] as ModelConfig
@@ -221,12 +226,17 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
 
   watch(
     sceneConfig,
-    (newValue) => {
+    async (newValue) => {
       if (load3d && nodeRef.value) {
         nodeRef.value.properties['Scene Config'] = newValue
         load3d.toggleGrid(newValue.showGrid)
         load3d.setBackgroundColor(newValue.backgroundColor)
-        void load3d.setBackgroundImage(newValue.backgroundImage || '')
+
+        await load3d.setBackgroundImage(newValue.backgroundImage || '')
+
+        if (newValue.backgroundRenderMode) {
+          load3d.setBackgroundRenderMode(newValue.backgroundRenderMode)
+        }
       }
     },
     { deep: true }
@@ -424,6 +434,9 @@ export const useLoad3d = (nodeOrRef: MaybeRef<LGraphNode | null>) => {
     backgroundColorChange: (value: string) => {
       sceneConfig.value.backgroundColor = value
     },
+    backgroundRenderModeChange: (value: string) => {
+      sceneConfig.value.backgroundRenderMode = value as 'tiled' | 'panorama'
+    },
     lightIntensityChange: (value: number) => {
       lightConfig.value.intensity = value
     },
diff --git a/src/composables/useLoad3dViewer.ts b/src/composables/useLoad3dViewer.ts
index fdf3fc760..93364a8ca 100644
--- a/src/composables/useLoad3dViewer.ts
+++ b/src/composables/useLoad3dViewer.ts
@@ -3,6 +3,7 @@ import { ref, toRaw, watch } from 'vue'
 import Load3d from '@/extensions/core/load3d/Load3d'
 import Load3dUtils from '@/extensions/core/load3d/Load3dUtils'
 import type {
+  BackgroundRenderModeType,
   CameraType,
   MaterialMode,
   UpDirection
@@ -21,6 +22,7 @@ interface Load3dViewerState {
   lightIntensity: number
   cameraState: any
   backgroundImage: string
+  backgroundRenderMode: BackgroundRenderModeType
   upDirection: UpDirection
   materialMode: MaterialMode
 }
@@ -33,6 +35,7 @@ export const useLoad3dViewer = (node: LGraphNode) => {
   const lightIntensity = ref(1)
   const backgroundImage = ref('')
   const hasBackgroundImage = ref(false)
+  const backgroundRenderMode = ref<BackgroundRenderModeType>('tiled')
   const upDirection = ref<UpDirection>('original')
   const materialMode = ref<MaterialMode>('original')
   const needApplyChanges = ref(true)
@@ -49,6 +52,7 @@ export const useLoad3dViewer = (node: LGraphNode) => {
     lightIntensity: 1,
     cameraState: null,
     backgroundImage: '',
+    backgroundRenderMode: 'tiled',
     upDirection: 'original',
     materialMode: 'original'
   })
@@ -124,6 +128,20 @@ export const useLoad3dViewer = (node: LGraphNode) => {
     }
   })
 
+  watch(backgroundRenderMode, (newValue) => {
+    if (!load3d) return
+    try {
+      load3d.setBackgroundRenderMode(newValue)
+    } catch (error) {
+      console.error('Error updating background render mode:', error)
+      useToastStore().addAlert(
+        t('toastMessages.failedToUpdateBackgroundRenderMode', {
+          mode: newValue
+        })
+      )
+    }
+  })
+
   watch(upDirection, (newValue) => {
     if (!load3d) return
     try {
@@ -180,6 +198,10 @@ export const useLoad3dViewer = (node: LGraphNode) => {
           source.sceneManager.currentBackgroundColor
         showGrid.value =
           sceneConfig.showGrid ?? source.sceneManager.gridHelper.visible
+        backgroundRenderMode.value =
+          sceneConfig.backgroundRenderMode ||
+          source.sceneManager.backgroundRenderMode ||
+          'tiled'
 
         const backgroundInfo = source.sceneManager.getCurrentBackgroundInfo()
         if (backgroundInfo.type === 'image' && sceneConfig.backgroundImage) {
@@ -219,6 +241,7 @@ export const useLoad3dViewer = (node: LGraphNode) => {
         lightIntensity: lightIntensity.value,
         cameraState: sourceCameraState,
         backgroundImage: backgroundImage.value,
+        backgroundRenderMode: backgroundRenderMode.value,
         upDirection: upDirection.value,
         materialMode: materialMode.value
       }
@@ -274,7 +297,8 @@ export const useLoad3dViewer = (node: LGraphNode) => {
       nodeValue.properties['Scene Config'] = {
         showGrid: initialState.value.showGrid,
         backgroundColor: initialState.value.backgroundColor,
-        backgroundImage: initialState.value.backgroundImage
+        backgroundImage: initialState.value.backgroundImage,
+        backgroundRenderMode: initialState.value.backgroundRenderMode
       }
 
       nodeValue.properties['Camera Config'] = {
@@ -309,7 +333,8 @@ export const useLoad3dViewer = (node: LGraphNode) => {
       nodeValue.properties['Scene Config'] = {
         showGrid: showGrid.value,
         backgroundColor: backgroundColor.value,
-        backgroundImage: backgroundImage.value
+        backgroundImage: backgroundImage.value,
+        backgroundRenderMode: backgroundRenderMode.value
       }
 
       nodeValue.properties['Camera Config'] = {
@@ -331,6 +356,7 @@ export const useLoad3dViewer = (node: LGraphNode) => {
     await useLoad3dService().copyLoad3dState(load3d, sourceLoad3d)
 
     await sourceLoad3d.setBackgroundImage(backgroundImage.value)
+    sourceLoad3d.setBackgroundRenderMode(backgroundRenderMode.value)
 
     sourceLoad3d.forceRender()
 
@@ -429,6 +455,7 @@ export const useLoad3dViewer = (node: LGraphNode) => {
     lightIntensity,
     backgroundImage,
     hasBackgroundImage,
+    backgroundRenderMode,
     upDirection,
     materialMode,
     needApplyChanges,
diff --git a/src/extensions/core/load3d/Load3DConfiguration.ts b/src/extensions/core/load3d/Load3DConfiguration.ts
index 2ef176ff7..a914de388 100644
--- a/src/extensions/core/load3d/Load3DConfiguration.ts
+++ b/src/extensions/core/load3d/Load3DConfiguration.ts
@@ -162,7 +162,11 @@ class Load3DConfiguration {
         return
       }
 
-      this.load3d.setBackgroundImage(config.backgroundImage)
+      void this.load3d.setBackgroundImage(config.backgroundImage)
+
+      if (config.backgroundRenderMode) {
+        this.load3d.setBackgroundRenderMode(config.backgroundRenderMode)
+      }
     }
   }
 
diff --git a/src/extensions/core/load3d/Load3d.ts b/src/extensions/core/load3d/Load3d.ts
index d26375f6a..686e0b135 100644
--- a/src/extensions/core/load3d/Load3d.ts
+++ b/src/extensions/core/load3d/Load3d.ts
@@ -510,6 +510,11 @@ class Load3d {
     this.forceRender()
   }
 
+  setBackgroundRenderMode(mode: 'tiled' | 'panorama'): void {
+    this.sceneManager.setBackgroundRenderMode(mode)
+    this.forceRender()
+  }
+
   toggleCamera(cameraType?: 'perspective' | 'orthographic'): void {
     this.cameraManager.toggleCamera(cameraType)
 
diff --git a/src/extensions/core/load3d/SceneManager.ts b/src/extensions/core/load3d/SceneManager.ts
index 2a05ed181..c03a43121 100644
--- a/src/extensions/core/load3d/SceneManager.ts
+++ b/src/extensions/core/load3d/SceneManager.ts
@@ -3,6 +3,7 @@ import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'
 
 import Load3dUtils from './Load3dUtils'
 import {
+  type BackgroundRenderModeType,
   type EventManagerInterface,
   type SceneManagerInterface
 } from './interfaces'
@@ -16,6 +17,8 @@ export class SceneManager implements SceneManagerInterface {
   backgroundMesh: THREE.Mesh | null = null
   backgroundTexture: THREE.Texture | null = null
 
+  backgroundRenderMode: 'tiled' | 'panorama' = 'tiled'
+
   backgroundColorMaterial: THREE.MeshBasicMaterial | null = null
   currentBackgroundType: 'color' | 'image' = 'color'
   currentBackgroundColor: string = '#282828'
@@ -89,6 +92,10 @@ export class SceneManager implements SceneManagerInterface {
       }
     }
 
+    if (this.scene.background) {
+      this.scene.background = null
+    }
+
     this.scene.clear()
   }
 
@@ -104,6 +111,15 @@ export class SceneManager implements SceneManagerInterface {
     this.currentBackgroundColor = color
     this.currentBackgroundType = 'color'
 
+    if (this.scene.background instanceof THREE.Texture) {
+      this.scene.background = null
+    }
+
+    if (this.backgroundRenderMode === 'panorama') {
+      this.backgroundRenderMode = 'tiled'
+      this.eventManager.emitEvent('backgroundRenderModeChange', 'tiled')
+    }
+
     if (!this.backgroundMesh || !this.backgroundColorMaterial) {
       this.initBackgroundScene()
     }
@@ -168,36 +184,41 @@ export class SceneManager implements SceneManagerInterface {
       this.backgroundTexture = texture
       this.currentBackgroundType = 'image'
 
-      if (!this.backgroundMesh) {
-        this.initBackgroundScene()
-      }
-
-      const imageMaterial = new THREE.MeshBasicMaterial({
-        map: texture,
-        transparent: true,
-        depthWrite: false,
-        depthTest: false,
-        side: THREE.DoubleSide
-      })
-
-      if (this.backgroundMesh) {
-        if (
-          this.backgroundMesh.material !== this.backgroundColorMaterial &&
-          this.backgroundMesh.material instanceof THREE.Material
-        ) {
-          this.backgroundMesh.material.dispose()
+      if (this.backgroundRenderMode === 'panorama') {
+        texture.mapping = THREE.EquirectangularReflectionMapping
+        this.scene.background = texture
+      } else {
+        if (!this.backgroundMesh) {
+          this.initBackgroundScene()
         }
 
-        this.backgroundMesh.material = imageMaterial
-        this.backgroundMesh.position.set(0, 0, 0)
-      }
+        const imageMaterial = new THREE.MeshBasicMaterial({
+          map: texture,
+          transparent: true,
+          depthWrite: false,
+          depthTest: false,
+          side: THREE.DoubleSide
+        })
 
-      this.updateBackgroundSize(
-        this.backgroundTexture,
-        this.backgroundMesh,
-        this.renderer.domElement.clientWidth,
-        this.renderer.domElement.clientHeight
-      )
+        if (this.backgroundMesh) {
+          if (
+            this.backgroundMesh.material !== this.backgroundColorMaterial &&
+            this.backgroundMesh.material instanceof THREE.Material
+          ) {
+            this.backgroundMesh.material.dispose()
+          }
+
+          this.backgroundMesh.material = imageMaterial
+          this.backgroundMesh.position.set(0, 0, 0)
+        }
+
+        this.updateBackgroundSize(
+          this.backgroundTexture,
+          this.backgroundMesh,
+          this.renderer.domElement.clientWidth,
+          this.renderer.domElement.clientHeight
+        )
+      }
 
       this.eventManager.emitEvent('backgroundImageChange', uploadPath)
       this.eventManager.emitEvent('backgroundImageLoadingEnd', null)
@@ -213,6 +234,35 @@ export class SceneManager implements SceneManagerInterface {
     this.eventManager.emitEvent('backgroundImageLoadingEnd', null)
   }
 
+  setBackgroundRenderMode(mode: BackgroundRenderModeType): void {
+    if (this.backgroundRenderMode === mode) return
+
+    this.backgroundRenderMode = mode
+
+    if (this.currentBackgroundType === 'image' && this.backgroundTexture) {
+      try {
+        if (mode === 'panorama') {
+          this.backgroundTexture.mapping =
+            THREE.EquirectangularReflectionMapping
+          this.scene.background = this.backgroundTexture
+        } else {
+          this.scene.background = null
+          if (
+            this.backgroundMesh &&
+            this.backgroundMesh.material instanceof THREE.MeshBasicMaterial
+          ) {
+            this.backgroundMesh.material.map = this.backgroundTexture
+            this.backgroundMesh.material.needsUpdate = true
+          }
+        }
+      } catch (error) {
+        console.error('Error set background render mode:', error)
+      }
+    }
+
+    this.eventManager.emitEvent('backgroundRenderModeChange', mode)
+  }
+
   updateBackgroundSize(
     backgroundTexture: THREE.Texture | null,
     backgroundMesh: THREE.Mesh | null,
@@ -254,7 +304,11 @@ export class SceneManager implements SceneManagerInterface {
   }
 
   renderBackground(): void {
-    if (this.backgroundMesh) {
+    if (
+      (this.backgroundRenderMode === 'tiled' ||
+        this.currentBackgroundType === 'color') &&
+      this.backgroundMesh
+    ) {
       const currentToneMapping = this.renderer.toneMapping
       const currentExposure = this.renderer.toneMappingExposure
 
diff --git a/src/extensions/core/load3d/interfaces.ts b/src/extensions/core/load3d/interfaces.ts
index 8a97d189e..b1be8af38 100644
--- a/src/extensions/core/load3d/interfaces.ts
+++ b/src/extensions/core/load3d/interfaces.ts
@@ -13,6 +13,7 @@ import { type CustomInputSpec } from '@/schemas/nodeDef/nodeDefSchemaV2'
 export type MaterialMode = 'original' | 'normal' | 'wireframe' | 'depth'
 export type UpDirection = 'original' | '-x' | '+x' | '-y' | '+y' | '-z' | '+z'
 export type CameraType = 'perspective' | 'orthographic'
+export type BackgroundRenderModeType = 'tiled' | 'panorama'
 
 export interface CameraState {
   position: THREE.Vector3
@@ -25,6 +26,7 @@ export interface SceneConfig {
   showGrid: boolean
   backgroundColor: string
   backgroundImage?: string
+  backgroundRenderMode?: BackgroundRenderModeType
 }
 
 export interface ModelConfig {
@@ -77,6 +79,7 @@ export interface SceneManagerInterface extends BaseManager {
   setBackgroundColor(color: string): void
   setBackgroundImage(uploadPath: string): Promise<void>
   removeBackgroundImage(): void
+  setBackgroundRenderMode(mode: BackgroundRenderModeType): void
   handleResize(width: number, height: number): void
   captureScene(width: number, height: number): Promise<CaptureResult>
 }
diff --git a/src/locales/en/main.json b/src/locales/en/main.json
index 5ef78eace..6f7baab19 100644
--- a/src/locales/en/main.json
+++ b/src/locales/en/main.json
@@ -1737,6 +1737,8 @@
     "previewOutput": "Preview Output",
     "uploadBackgroundImage": "Upload Background Image",
     "removeBackgroundImage": "Remove Background Image",
+    "tiledMode": "Tiled",
+    "panoramaMode": "Panorama",
     "loadingModel": "Loading 3D Model...",
     "upDirection": "Up Direction",
     "materialMode": "Material Mode",
@@ -1833,7 +1835,8 @@
     "failedToInitializeLoad3dViewer": "Failed to initialize 3D Viewer",
     "failedToLoadBackgroundImage": "Failed to load background image",
     "failedToLoadModel": "Failed to load 3D model",
-    "modelLoadedSuccessfully": "3D model loaded successfully"
+    "modelLoadedSuccessfully": "3D model loaded successfully",
+    "failedToUpdateBackgroundRenderMode": "Failed to update background render mode to {mode}"
   },
   "auth": {
     "apiKey": {
diff --git a/tests-ui/tests/composables/useLoad3d.test.ts b/tests-ui/tests/composables/useLoad3d.test.ts
index 5462922db..fadafa4f8 100644
--- a/tests-ui/tests/composables/useLoad3d.test.ts
+++ b/tests-ui/tests/composables/useLoad3d.test.ts
@@ -47,7 +47,8 @@ describe('useLoad3d', () => {
         'Scene Config': {
           showGrid: true,
           backgroundColor: '#000000',
-          backgroundImage: ''
+          backgroundImage: '',
+          backgroundRenderMode: 'tiled'
         },
         'Model Config': {
           upDirection: 'original',
@@ -81,6 +82,7 @@ describe('useLoad3d', () => {
       toggleGrid: vi.fn(),
       setBackgroundColor: vi.fn(),
       setBackgroundImage: vi.fn().mockResolvedValue(undefined),
+      setBackgroundRenderMode: vi.fn(),
       setUpDirection: vi.fn(),
       setMaterialMode: vi.fn(),
       toggleCamera: vi.fn(),
@@ -130,7 +132,8 @@ describe('useLoad3d', () => {
       expect(composable.sceneConfig.value).toEqual({
         showGrid: true,
         backgroundColor: '#000000',
-        backgroundImage: ''
+        backgroundImage: '',
+        backgroundRenderMode: 'tiled'
       })
       expect(composable.modelConfig.value).toEqual({
         upDirection: 'original',
@@ -165,9 +168,11 @@ describe('useLoad3d', () => {
       const containerRef = document.createElement('div')
 
       await composable.initializeLoad3d(containerRef)
+      await nextTick()
 
       expect(mockLoad3d.toggleGrid).toHaveBeenCalledWith(true)
       expect(mockLoad3d.setBackgroundColor).toHaveBeenCalledWith('#000000')
+      expect(mockLoad3d.setBackgroundRenderMode).toHaveBeenCalledWith('tiled')
       expect(mockLoad3d.setUpDirection).toHaveBeenCalledWith('original')
       expect(mockLoad3d.setMaterialMode).toHaveBeenCalledWith('original')
       expect(mockLoad3d.toggleCamera).toHaveBeenCalledWith('perspective')
@@ -356,17 +361,22 @@ describe('useLoad3d', () => {
       composable.sceneConfig.value = {
         showGrid: false,
         backgroundColor: '#ffffff',
-        backgroundImage: 'test.jpg'
+        backgroundImage: 'test.jpg',
+        backgroundRenderMode: 'panorama'
       }
       await nextTick()
 
       expect(mockLoad3d.toggleGrid).toHaveBeenCalledWith(false)
       expect(mockLoad3d.setBackgroundColor).toHaveBeenCalledWith('#ffffff')
       expect(mockLoad3d.setBackgroundImage).toHaveBeenCalledWith('test.jpg')
+      expect(mockLoad3d.setBackgroundRenderMode).toHaveBeenCalledWith(
+        'panorama'
+      )
       expect(mockNode.properties['Scene Config']).toEqual({
         showGrid: false,
         backgroundColor: '#ffffff',
-        backgroundImage: 'test.jpg'
+        backgroundImage: 'test.jpg',
+        backgroundRenderMode: 'panorama'
       })
     })
 
@@ -375,6 +385,10 @@ describe('useLoad3d', () => {
       const containerRef = document.createElement('div')
 
       await composable.initializeLoad3d(containerRef)
+      await nextTick()
+
+      mockLoad3d.setUpDirection.mockClear()
+      mockLoad3d.setMaterialMode.mockClear()
 
       composable.modelConfig.value.upDirection = '+y'
       composable.modelConfig.value.materialMode = 'wireframe'
@@ -393,6 +407,10 @@ describe('useLoad3d', () => {
       const containerRef = document.createElement('div')
 
       await composable.initializeLoad3d(containerRef)
+      await nextTick()
+
+      mockLoad3d.toggleCamera.mockClear()
+      mockLoad3d.setFOV.mockClear()
 
       composable.cameraConfig.value.cameraType = 'orthographic'
       composable.cameraConfig.value.fov = 90
@@ -412,6 +430,9 @@ describe('useLoad3d', () => {
       const containerRef = document.createElement('div')
 
       await composable.initializeLoad3d(containerRef)
+      await nextTick()
+
+      mockLoad3d.setLightIntensity.mockClear()
 
       composable.lightConfig.value.intensity = 10
       await nextTick()
@@ -652,6 +673,7 @@ describe('useLoad3d', () => {
       const expectedEvents = [
         'materialModeChange',
         'backgroundColorChange',
+        'backgroundRenderModeChange',
         'lightIntensityChange',
         'fovChange',
         'cameraTypeChange',
diff --git a/tests-ui/tests/composables/useLoad3dViewer.test.ts b/tests-ui/tests/composables/useLoad3dViewer.test.ts
index 589297977..4ec2d7798 100644
--- a/tests-ui/tests/composables/useLoad3dViewer.test.ts
+++ b/tests-ui/tests/composables/useLoad3dViewer.test.ts
@@ -44,7 +44,8 @@ describe('useLoad3dViewer', () => {
         'Scene Config': {
           backgroundColor: '#282828',
           showGrid: true,
-          backgroundImage: ''
+          backgroundImage: '',
+          backgroundRenderMode: 'tiled'
         },
         'Camera Config': {
           cameraType: 'perspective',
@@ -115,6 +116,7 @@ describe('useLoad3dViewer', () => {
         materialMode: 'original'
       },
       setBackgroundImage: vi.fn().mockResolvedValue(undefined),
+      setBackgroundRenderMode: vi.fn(),
       forceRender: vi.fn()
     }