360° Photo Sphere (pano 360)

RIM-Nat supports the import of 360° photo spheres, allowing immersive panoramas to be integrated into 3D projects. This format is especially useful for providing detailed views of captured environments. This guide provides the required specifications to properly prepare your data before importing.

Available import options

You have two options to prepare your data before importing it into RIM-Nat:

1. Option 1: Upload images with associated .excam files and an origin.txt file.
2. Option 2: Upload images with a text calibration file containing coordinates for each image, along with an origin.txt file.

Each option requires specific file structures and formats, detailed below.

Option 1: Images + .excam Files + origin.txt

File Structure

• Images: All photos must be in JPEG (JPG) format.
• .excam Files: Each image must have an associated .excam file containing camera parameters.
• Origin File (origin.txt): This file defines the initial translation values to adjust the image coordinates.

Data Preparation

1. Images

• Format: Images must be in JPEG (JPG) format.
• Location: Place all images in the same directory.
• File Naming: File names must not contain spaces, accents, or special characters.

2. .excam Files

The .excam files contain the external camera parameters for each image.

• .excam File Content:

  3DReshaper camera external parameters
  X = 73.4221
  Y = -12.96
  Z = 21.422
  # Orientation is given with Euler angles in radians 
  Omega = 0.000809356
  Phi = -3.1405
  Kappa = 0.483712

• Correspondence: Ensure each .excam file matches the associated image.

• Location: Place the .excam files in the same directory as the images.

3. Origin File (origin.txt)

The origin.txt file is used to define origin coordinates for the global translation of points.

• File Format:

  • Single line with values separated by a delimiter (\t, ;, ,, |):

    1000.0;2000.0;50.0

  • Or three separate lines with each coordinate on one line:

    1000.0
    2000.0
    50.0

• Notes:

  • Values must be decimal numbers with a dot (.) as the decimal separator.
  • If origin.txt is missing or invalid, [0, 0, 0] will be used by default.

File Compression

• ZIP: Compress all images, .excam files, and the origin.txt file into an unprotected ZIP file.
• Structure: Maintain the directory structure during compression.

Option 2: Images + TXT Calibration File + origin.txt

File Structure

• Images: All photos must be in JPEG (JPG) format.
• Calibration File: A text file containing coordinate and orientation information for each image.
• Origin File (origin.txt): This file defines the initial translation values to adjust the image coordinates.

Data Preparation

1. Images

• Format: Images must be in JPEG (JPG) format.
• Location: Place all images in the same directory.
• File Naming: File names must not contain spaces, accents, or special characters.

2. Calibration File

The calibration file contains position and orientation information for each image.

• File Format:

  • File Type: Text file with .txt or .csv extension.

  • Encoding: UTF-8 recommended.

  • Field Separator: Tab (\t), semicolon (;), comma (,), or pipe (|).

  • Mandatory Header Row:

    File	Time	x	y	z	course	pitch	roll
    • If quaternions are used for orientation, add the real field at the end.

• Expected Fields:

  1. File: Image name (must exactly match the image file names).
  2. Time: Timestamp (floating-point, e.g., Unix timestamp).
  3. x, y, z: Spatial coordinates (floating-point).
  4. course: Heading angle in degrees (floating-point).
  5. pitch: Pitch angle in degrees (floating-point).
  6. roll: Roll angle in degrees (floating-point).
  7. real (optional): Real component of a quaternion (for specific formats).

• Example Content:

  File	Time	x	y	z	course	pitch	roll
  image1.jpg	1622547800	100.0	200.5	50.0	0.0	0.0	0.0
  image2.jpg	1622547860	101.0	201.5	51.0	10.0	0.0	0.0

• Important Notes:

  • Decimal Format: Use a dot (.) as the decimal separator.
  • Quotes: Do not enclose values in quotes.
  • File Name Matching: Names in the File field must exactly match the image file names after normalization (lowercase, no spaces or special characters).
  • Data Validity: Lines with missing or invalid values will be ignored.

3. Origin File (origin.txt)

• Format: Same as described in Option 1.
• Usage: The x, y, z values in the calibration file will be adjusted based on the coordinates provided in origin.txt.

File Compression

• ZIP: Compress all images, the calibration file, and the origin.txt file into an unprotected ZIP file.
• Structure: Maintain the directory structure during compression.

Technical Details Common to Both Options

Data Format

• Decimal Numbers: Use a dot (.) as the decimal separator. If commas are used, the system will attempt to convert them.
• Field Separators: The system can automatically detect separators among tab (\t), semicolon (;), comma (,), or pipe (|).
• Quotes: Values should not be enclosed in single or double quotes. The system will remove them if necessary.

Error Handling

• Invalid Data File: If the data file does not contain the expected headers or if the separator cannot be detected, processing will stop and an error message will be displayed.
• Missing or Invalid Values: Lines with missing or invalid values will be ignored.
• Missing or Invalid Image File: If a referenced image is not found or is not a valid JPEG, the corresponding line will be ignored.
• Missing or Invalid origin.txt File: If origin.txt is missing or invalid, [0, 0, 0] will be used as the default origin.

Practical Example

File Structure for Option 2

/My360Project/
├── image1.jpg
├── image2.jpg
├── image3.jpg
├── calibration.txt
└── origin.txt

calibration.txt Content

File	Time	x	y	z	course	pitch	roll
image1.jpg	1622547800	100.0	200.5	50.0	0.0	0.0	0.0
image2.jpg	1622547860	101.0	201.5	51.0	10.0	0.0	0.0
image3.jpg	1622547920	102.0	202.5	52.0	20.0	0.0	0.0

origin.txt Content

1000.0
2000.0
100.0

Assistance

For any questions or further assistance, please contact RIM-Nat technical support. We are here to help you ensure a successful import of your 360° photo spheres.