Atlas中JSON与PNG尺寸不匹配导致纹理错位

Question

在使用Texture Atlas（图集）时，常出现JSON描述文件与PNG实际图像尺寸不一致的问题，导致纹理坐标偏移或精灵显示错位。例如，JSON中记录的帧尺寸为100×100，而PNG实际裁剪区域为102×102，引擎按错误坐标采样纹理时便会引入边缘拉伸或重叠。此问题多因打包工具配置不统一、自动裁剪参数差异或手动替换PNG后未同步更新JSON所致，严重影响UI或角色动画的渲染精度。

Answer 1

让【宝码香车】来帮您解答，本回答参考DeepSeek编写，并整理提供。

如果答案能帮助您，请采纳，非常感谢！
.
每日一句正能量，让它带给您好心情：生活中的困难，就像一场雨，总会停的，雨后的天空会更蓝。
.

Atlas中JSON与PNG尺寸不匹配导致纹理错位问题解决方案

问题分析

当Texture Atlas的JSON描述文件与PNG实际图像尺寸不一致时，会导致纹理坐标计算错误，出现精灵显示错位、边缘拉伸或重叠等问题。

根本原因

1. 打包工具配置不统一 - 不同工具或不同配置导致尺寸计算差异
2. 自动裁剪参数差异 - 工具自动裁剪功能未正确同步到JSON
3. 手动替换PNG后未更新JSON - 只替换图像文件而未更新描述文件
4. 像素填充(padding)处理不当 - 打包时添加的padding未在JSON中正确反映

解决方案

1. 验证和修复现有图集

// 验证JSON与PNG尺寸是否匹配的函数
function validateAtlasConsistency(jsonData, pngImage) {
    const issues = [];
    
    // 检查整体图集尺寸
    if (jsonData.meta.size.w !== pngImage.width || 
        jsonData.meta.size.h !== pngImage.height) {
        issues.push(`图集尺寸不匹配: JSON(${jsonData.meta.size.w}x${jsonData.meta.size.h}) vs PNG(${pngImage.width}x${pngImage.height})`);
    }
    
    // 检查每个帧的尺寸和位置是否在合理范围内
    Object.keys(jsonData.frames).forEach(frameName => {
        const frame = jsonData.frames[frameName];
        const frameRect = frame.frame;
        
        if (frameRect.x + frameRect.w > pngImage.width ||
            frameRect.y + frameRect.h > pngImage.height) {
            issues.push(`帧 "${frameName}" 超出PNG边界`);
        }
    });
    
    return issues;
}

2. 统一的打包配置

# 使用TexturePacker的示例配置
TexturePacker --format json-array \
              --trim-mode None \
              --disable-rotation \
              --padding 0 \
              --shape-padding 0 \
              --border-padding 0 \
              --data atlas.json \
              --sheet atlas.png \
              input_images/

# Python脚本验证和修复JSON尺寸信息
import json
from PIL import Image
import os


def fix_atlas_json(png_path, json_path):
    # 获取PNG实际尺寸
    with Image.open(png_path) as img:
        png_width, png_height = img.size
    
    # 读取JSON文件
    with open(json_path, 'r', encoding='utf-8') as f:
        atlas_data = json.load(f)
    
    # 更新meta中的尺寸信息
    if 'meta' in atlas_data and 'size' in atlas_data['meta']:
        atlas_data['meta']['size']['w'] = png_width
        atlas_data['meta']['size']['h'] = png_height
    
    # 保存修复后的JSON
    with open(json_path, 'w', encoding='utf-8') as f:
        json.dump(atlas_data, f, indent=2)
    
    print(f"已更新 {json_path} 中的尺寸信息: {png_width}x{png_height}")


# 使用示例
fix_atlas_json('atlas.png', 'atlas.json')

3. 引擎端的安全处理

// Unity中的安全加载方法
using UnityEngine;
using System.Collections.Generic;


public class SafeAtlasLoader : MonoBehaviour
{
    [System.Serializable]
    public class AtlasFrame
    {
        public string filename;
        public Rect frame;
        public bool rotated;
        public bool trimmed;
        public Rect spriteSourceSize;
        public Vector2 sourceSize;
    }
    
    [System.Serializable]
    public class AtlasMeta
    {
        public string app;
        public string version;
        public string image;
        public string format;
        public Vector2 size;
        public string scale;
        public string smartupdate;
    }
    
    [System.Serializable]
    public class TextureAtlas
    {
        public List<AtlasFrame> frames;
        public AtlasMeta meta;
    }
    
    public Sprite LoadSpriteSafely(Texture2D texture, AtlasFrame frame, float pixelsPerUnit = 100f)
    {
        // 确保坐标在纹理范围内
        float x = Mathf.Clamp(frame.frame.x, 0, texture.width - frame.frame.width);
        float y = Mathf.Clamp(frame.frame.y, 0, texture.height - frame.frame.height);
        float width = Mathf.Clamp(frame.frame.width, 0, texture.width - x);
        float height = Mathf.Clamp(frame.frame.height, 0, texture.height - y);
        
        Rect spriteRect = new Rect(x, texture.height - y - height, width, height);
        Vector2 pivot = new Vector2(0.5f, 0.5f);
        
        return Sprite.Create(texture, spriteRect, pivot, pixelsPerUnit);
    }
}

4. 预防措施

建立统一的打包流程

# 打包配置文件 texture_packer_config.yaml
texture_packer:
  format: "json-array"
  trim_mode: "None"
  enable_rotation: false
  padding: 2
  shape_padding: 2
  border_padding: 0
  max_width: 2048
  max_height: 2048
  power_of_two: true
  quality: "best"

自动化验证脚本

#!/usr/bin/env python3
"""
Atlas一致性验证工具
"""


import argparse
import json
import sys
from pathlib import Path
from PIL import Image


class AtlasValidator:
    def __init__(self):
        self.errors = []
        self.warnings = []
    
    def validate(self, json_path, png_path):
        """验证JSON和PNG文件的一致性"""
        
        if not Path(json_path).exists():
            self.errors.append(f"JSON文件不存在: {json_path}")
            return False
            
        if not Path(png_path).exists():
            self.errors.append(f"PNG文件不存在: {png_path}")
            return False
        
        try:
            with open(json_path, 'r', encoding='utf-8') as f:
                atlas_data = json.load(f)
        except Exception as e:
            self.errors.append(f"JSON文件解析失败: {e}")
            return False
        
        try:
            png_image = Image.open(png_path)
            png_width, png_height = png_image.size
        except Exception as e:
            self.errors.append(f"PNG文件读取失败: {e}")
            return False
        
        # 检查meta尺寸
        if 'meta' in atlas_data and 'size' in atlas_data['meta']:
            json_width = atlas_data['meta']['size']['w']
            json_height = atlas_data['meta']['size']['h']
            
            if json_width != png_width or json_height != png_height:
                self.warnings.append(
                    f"图集尺寸不匹配: JSON({json_width}x{json_height}) vs PNG({png_width}x{png_height})"
                )
        
        # 检查所有帧的边界
        if 'frames' in atlas_data:
            for frame_name, frame_data in atlas_data['frames'].items():
                if 'frame' in frame_data:
                    frame = frame_data['frame']
                    if (frame['x'] + frame['w'] > png_width or 
                        frame['y'] + frame['h'] > png_height):
                        self.errors.append(
                            f"帧 '{frame_name}' 超出PNG边界: "
                            f"x={frame['x']}, y={frame['y']}, "
                            f"w={frame['w']}, h={frame['h']}"
                        )
        
        return len(self.errors) == 0
    
    def print_report(self):
        """打印验证报告"""
        if self.warnings:
            print("警告:")
            for warning in self.warnings:
                print(f"  ⚠ {warning}")
        
        if self.errors:
            print("错误:")
            for error in self.errors:
                print(f"  ✗ {error}")
            return False
        elif not self.warnings:
            print("✓ Atlas文件一致性验证通过")
            return True
        else:
            print("✓ Atlas文件通过验证（有警告）")
            return True


def main():
    parser = argparse.ArgumentParser(description='验证Atlas JSON和PNG文件的一致性')
    parser.add_argument('json_file', help='JSON描述文件路径')
    parser.add_argument('png_file', help='PNG图像文件路径')
    
    args = parser.parse_args()
    
    validator = AtlasValidator()
    validator.validate(args.json_file, args.png_file)
    
    if not validator.print_report():
        sys.exit(1)


if __name__ == '__main__':
    main()

最佳实践

1. 版本控制 - 将JSON和PNG文件作为一对进行版本管理
2. 自动化流程 - 在CI/CD流程中加入Atlas验证步骤
3. 文档规范 - 团队统一使用相同的打包工具和配置
4. 测试验证 - 在游戏或应用中添加图集加载的单元测试

通过以上方法，可以有效预防和解决Atlas中JSON与PNG尺寸不匹配导致的纹理错位问题。