The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.
feat(jobs): add 3d to PREVIEWABLE_MEDIA_TYPES for first-class 3D output support (#12381)
guill00fff6019ecf
diff --git a/comfy_execution/jobs.py b/comfy_execution/jobs.pyindex bf091a448..370014fb6 100644--- a/comfy_execution/jobs.py+++ b/comfy_execution/jobs.py@@ -20,10 +20,60 @@ class JobStatus:# Media types that can be previewed in the frontend-PREVIEWABLE_MEDIA_TYPES = frozenset({'images', 'video', 'audio'})+PREVIEWABLE_MEDIA_TYPES = frozenset({'images', 'video', 'audio', '3d'})# 3D file extensions for preview fallback (no dedicated media_type exists)-THREE_D_EXTENSIONS = frozenset({'.obj', '.fbx', '.gltf', '.glb'})+THREE_D_EXTENSIONS = frozenset({'.obj', '.fbx', '.gltf', '.glb', '.usdz'})+++def has_3d_extension(filename: str) -> bool:+ lower = filename.lower()+ return any(lower.endswith(ext) for ext in THREE_D_EXTENSIONS)+++def normalize_output_item(item):+ """Normalize a single output list item for the jobs API.++ Returns the normalized item, or None to exclude it.+ String items with 3D extensions become {filename, type, subfolder} dicts.+ """+ if item is None:+ return None+ if isinstance(item, str):+ if has_3d_extension(item):+ return {'filename': item, 'type': 'output', 'subfolder': '', 'mediaType': '3d'}+ return None+ if isinstance(item, dict):+ return item+ return None+++def normalize_outputs(outputs: dict) -> dict:+ """Normalize raw node outputs for the jobs API.++ Transforms string 3D filenames into file output dicts and removes+ None items. All other items (non-3D strings, dicts, etc.) are+ preserved as-is.+ """+ normalized = {}+ for node_id, node_outputs in outputs.items():+ if not isinstance(node_outputs, dict):+ normalized[node_id] = node_outputs+ continue+ normalized_node = {}+ for media_type, items in node_outputs.items():+ if media_type == 'animated' or not isinstance(items, list):+ normalized_node[media_type] = items+ continue+ normalized_items = []+ for item in items:+ if item is None:+ continue+ norm = normalize_output_item(item)+ normalized_items.append(norm if norm is not None else item)+ normalized_node[media_type] = normalized_items+ normalized[node_id] = normalized_node+ return normalizeddef _extract_job_metadata(extra_data: dict) -> tuple[Optional[int], Optional[str]]:@@ -45,9 +95,9 @@ def is_previewable(media_type: str, item: dict) -> bool:Maintains backwards compatibility with existing logic.Priority:- 1. media_type is 'images', 'video', or 'audio'+ 1. media_type is 'images', 'video', 'audio', or '3d'2. format field starts with 'video/' or 'audio/'- 3. filename has a 3D extension (.obj, .fbx, .gltf, .glb)+ 3. filename has a 3D extension (.obj, .fbx, .gltf, .glb, .usdz)"""if media_type in PREVIEWABLE_MEDIA_TYPES:return True@@ -139,7 +189,7 @@ def normalize_history_item(prompt_id: str, history_item: dict, include_outputs:})if include_outputs:- job['outputs'] = outputs+ job['outputs'] = normalize_outputs(outputs)job['execution_status'] = status_infojob['workflow'] = {'prompt': prompt,@@ -171,18 +221,23 @@ def get_outputs_summary(outputs: dict) -> tuple[int, Optional[dict]]:continuefor item in items:+ normalized = normalize_output_item(item)+ if normalized is None:+ continue+count += 1- if not isinstance(item, dict):+ if preview_output is not None:continue- if preview_output is None and is_previewable(media_type, item):+ if isinstance(normalized, dict) and is_previewable(media_type, normalized):enriched = {- **item,+ **normalized,'nodeId': node_id,- 'mediaType': media_type}- if item.get('type') == 'output':+ if 'mediaType' not in normalized:+ enriched['mediaType'] = media_type+ if normalized.get('type') == 'output':preview_output = enrichedelif fallback_preview is None:fallback_preview = enricheddiff --git a/tests/execution/test_jobs.py b/tests/execution/test_jobs.pyindex 4d2f9ed36..83c36fe48 100644--- a/tests/execution/test_jobs.py+++ b/tests/execution/test_jobs.py@@ -5,8 +5,11 @@ from comfy_execution.jobs import (is_previewable,normalize_queue_item,normalize_history_item,+ normalize_output_item,+ normalize_outputs,get_outputs_summary,apply_sorting,+ has_3d_extension,)@@ -35,8 +38,8 @@ class TestIsPreviewable:"""Unit tests for is_previewable()"""def test_previewable_media_types(self):- """Images, video, audio media types should be previewable."""- for media_type in ['images', 'video', 'audio']:+ """Images, video, audio, 3d media types should be previewable."""+ for media_type in ['images', 'video', 'audio', '3d']:assert is_previewable(media_type, {}) is Truedef test_non_previewable_media_types(self):@@ -46,7 +49,7 @@ class TestIsPreviewable:def test_3d_extensions_previewable(self):"""3D file extensions should be previewable regardless of media_type."""- for ext in ['.obj', '.fbx', '.gltf', '.glb']:+ for ext in ['.obj', '.fbx', '.gltf', '.glb', '.usdz']:item = {'filename': f'model{ext}'}assert is_previewable('files', item) is True@@ -160,7 +163,7 @@ class TestGetOutputsSummary:def test_3d_files_previewable(self):"""3D file extensions should be previewable."""- for ext in ['.obj', '.fbx', '.gltf', '.glb']:+ for ext in ['.obj', '.fbx', '.gltf', '.glb', '.usdz']:outputs = {'node1': {'files': [{'filename': f'model{ext}', 'type': 'output'}]@@ -192,6 +195,64 @@ class TestGetOutputsSummary:assert preview['mediaType'] == 'images'assert preview['subfolder'] == 'outputs'+ def test_string_3d_filename_creates_preview(self):+ """String items with 3D extensions should synthesize a preview (Preview3D node output).+ Only the .glb counts — nulls and non-file strings are excluded."""+ outputs = {+ 'node1': {+ 'result': ['preview3d_abc123.glb', None, None]+ }+ }+ count, preview = get_outputs_summary(outputs)+ assert count == 1+ assert preview is not None+ assert preview['filename'] == 'preview3d_abc123.glb'+ assert preview['mediaType'] == '3d'+ assert preview['nodeId'] == 'node1'+ assert preview['type'] == 'output'++ def test_string_non_3d_filename_no_preview(self):+ """String items without 3D extensions should not create a preview."""+ outputs = {+ 'node1': {+ 'result': ['data.json', None]+ }+ }+ count, preview = get_outputs_summary(outputs)+ assert count == 0+ assert preview is None++ def test_string_3d_filename_used_as_fallback(self):+ """String 3D preview should be used when no dict items are previewable."""+ outputs = {+ 'node1': {+ 'latents': [{'filename': 'latent.safetensors'}],+ },+ 'node2': {+ 'result': ['model.glb', None]+ }+ }+ count, preview = get_outputs_summary(outputs)+ assert preview is not None+ assert preview['filename'] == 'model.glb'+ assert preview['mediaType'] == '3d'+++class TestHas3DExtension:+ """Unit tests for has_3d_extension()"""++ def test_recognized_extensions(self):+ for ext in ['.obj', '.fbx', '.gltf', '.glb', '.usdz']:+ assert has_3d_extension(f'model{ext}') is True++ def test_case_insensitive(self):+ assert has_3d_extension('MODEL.GLB') is True+ assert has_3d_extension('Scene.GLTF') is True++ def test_non_3d_extensions(self):+ for name in ['photo.png', 'video.mp4', 'data.json', 'model']:+ assert has_3d_extension(name) is False+class TestApplySorting:"""Unit tests for apply_sorting()"""@@ -395,3 +456,142 @@ class TestNormalizeHistoryItem:'prompt': {'nodes': {'1': {}}},'extra_data': {'create_time': 1234567890, 'client_id': 'abc'},}++ def test_include_outputs_normalizes_3d_strings(self):+ """Detail view should transform string 3D filenames into file output dicts."""+ history_item = {+ 'prompt': (+ 5,+ 'prompt-3d',+ {'nodes': {}},+ {'create_time': 1234567890},+ ['node1'],+ ),+ 'status': {'status_str': 'success', 'completed': True, 'messages': []},+ 'outputs': {+ 'node1': {+ 'result': ['preview3d_abc123.glb', None, None]+ }+ },+ }+ job = normalize_history_item('prompt-3d', history_item, include_outputs=True)++ assert job['outputs_count'] == 1+ result_items = job['outputs']['node1']['result']+ assert len(result_items) == 1+ assert result_items[0] == {+ 'filename': 'preview3d_abc123.glb',+ 'type': 'output',+ 'subfolder': '',+ 'mediaType': '3d',+ }++ def test_include_outputs_preserves_dict_items(self):+ """Detail view normalization should pass dict items through unchanged."""+ history_item = {+ 'prompt': (+ 5,+ 'prompt-img',+ {'nodes': {}},+ {'create_time': 1234567890},+ ['node1'],+ ),+ 'status': {'status_str': 'success', 'completed': True, 'messages': []},+ 'outputs': {+ 'node1': {+ 'images': [+ {'filename': 'photo.png', 'type': 'output', 'subfolder': ''},+ ]+ }+ },+ }+ job = normalize_history_item('prompt-img', history_item, include_outputs=True)++ assert job['outputs_count'] == 1+ assert job['outputs']['node1']['images'] == [+ {'filename': 'photo.png', 'type': 'output', 'subfolder': ''},+ ]+++class TestNormalizeOutputItem:+ """Unit tests for normalize_output_item()"""++ def test_none_returns_none(self):+ assert normalize_output_item(None) is None++ def test_string_3d_extension_synthesizes_dict(self):+ result = normalize_output_item('model.glb')+ assert result == {'filename': 'model.glb', 'type': 'output', 'subfolder': '', 'mediaType': '3d'}++ def test_string_non_3d_extension_returns_none(self):+ assert normalize_output_item('data.json') is None++ def test_string_no_extension_returns_none(self):+ assert normalize_output_item('camera_info_string') is None++ def test_dict_passes_through(self):+ item = {'filename': 'test.png', 'type': 'output'}+ assert normalize_output_item(item) is item++ def test_other_types_return_none(self):+ assert normalize_output_item(42) is None+ assert normalize_output_item(True) is None+++class TestNormalizeOutputs:+ """Unit tests for normalize_outputs()"""++ def test_empty_outputs(self):+ assert normalize_outputs({}) == {}++ def test_dict_items_pass_through(self):+ outputs = {+ 'node1': {+ 'images': [{'filename': 'a.png', 'type': 'output'}],+ }+ }+ result = normalize_outputs(outputs)+ assert result == outputs++ def test_3d_string_synthesized(self):+ outputs = {+ 'node1': {+ 'result': ['model.glb', None, None],+ }+ }+ result = normalize_outputs(outputs)+ assert result == {+ 'node1': {+ 'result': [+ {'filename': 'model.glb', 'type': 'output', 'subfolder': '', 'mediaType': '3d'},+ ],+ }+ }++ def test_animated_key_preserved(self):+ outputs = {+ 'node1': {+ 'images': [{'filename': 'a.png', 'type': 'output'}],+ 'animated': [True],+ }+ }+ result = normalize_outputs(outputs)+ assert result['node1']['animated'] == [True]++ def test_non_dict_node_outputs_preserved(self):+ outputs = {'node1': 'unexpected_value'}+ result = normalize_outputs(outputs)+ assert result == {'node1': 'unexpected_value'}++ def test_none_items_filtered_but_other_types_preserved(self):+ outputs = {+ 'node1': {+ 'result': ['data.json', None, [1, 2, 3]],+ }+ }+ result = normalize_outputs(outputs)+ assert result == {+ 'node1': {+ 'result': ['data.json', [1, 2, 3]],+ }+ }