Report: Various issues with image writing methods

SketchUp Ruby API Issues

An attempt to write out a texture as a psd file failed and instigated this report. Because documentation was poor, I had to test the support for psd files. I came across multiple issues with multiple methods as described below.

The kinds if issues:

Inconsistent or incorrect exceptions
Supported output image filetypes not listed for many methods
Many methods are creating empty (invalid) files for unsupported filetypes
Several methods have no return value documented
Several method say nothing but "(Boolean)" for return documentation

Ref: Issue #57

Also see ISSUE BREAKDOWN (next post)

EXPORT TESTS

TESTDIR = "D:/DOCUMENTS/SketchUp/ExportTest/PSD"
CAPTION = "Save psd test ..."

# Sketchup::save_thumbnail()
# Doc: No supported filetypes listed.
  Sketchup::save_thumbnail(
    Sketchup.active_model.path,
   UI.savepanel(CAPTION,TESTDIR,"psd_test_sketchup_save_thumbnail.psd")
  )
  #=> false
  # writes 0 bytesize psd file

# Sketchup::ComponentDefinition#save_thumbnail()
# Doc: Supported image formats are bmp, jpg, png, tif, pct, and gif.
# File: Should not be writing empty files for unsupported filetypes.
  Sketchup.active_model.definitions[0].save_thumbnail(
    UI.savepanel(CAPTION,TESTDIR,"psd_test_definition_save_thumbnail.psd")
  )
  #=> false
  # writes 0 bytesize psd file

# Sketchup::ImageRep.save_file()
# Doc: No supported filetypes listed.
# Doc: No return type specified.
# Error: Should raise ArgumentError ("Unsupported file extension")
#   not RuntimeError with a vague "failed to save file" message.
#   See: `Sketchup::Model#export()` error handling for precedent.
# File: Should not be writing empty files of any kind on error.
# File: Should not be writing empty files for unsupported filetypes.
  Sketchup.active_model.materials[0].texture.image_rep.save_file(
    UI.savepanel(CAPTION,TESTDIR,"psd_test_image_rep_save_file.psd")
  )
  #=> Error: #<RuntimeError: failed to save image>
  # writes 0 bytesize psd file

# Sketchup::Material#write_thumbnail
# Doc: No supported filetypes listed.
# File: Should not be writing empty files for unsupported filetypes.
  Sketchup.active_model.materials[0].write_thumbnail(
    UI.savepanel(CAPTION,TESTDIR,"psd_test_material_write_thumbnail.psd"), 128
  )
  #=> false
  # writes 0 bytesize psd file

# Sketchup::Model#save_thumbnail()
# Doc: Supported image formats are bmp, jpg, png, tif, pct, and gif.
# File: Should not be writing empty files for unsupported filetypes.
  Sketchup.active_model.save_thumbnail(
    UI.savepanel(CAPTION,TESTDIR,"psd_test_model_save_thumbnail.psd")
  )
  #=> false
  # writes 0 bytesize psd file

# Sketchup::Model#export()
# Doc: "SketchUp Free" should be "SketchUp Make" or "non-Pro editions".
# Doc: Separate non-Pro export formats from Pro. (It has been complained
#   in the forum that it is not clear that IFC and PDF are Pro only.)
  Sketchup.active_model.export(
    UI.savepanel(CAPTION,TESTDIR,"psd_test_model_export.psd")
  )
  #=> Error: #<ArgumentError: Unsupported file extension>
  # no file written

# Sketchup::Texture.write()
# Doc: No supported filetypes listed.
# File: Should not be writing empty files for unsupported filetypes.
  Sketchup.active_model.materials[0].texture.write(
    UI.savepanel(CAPTION,TESTDIR,"psd_test_texture_write_true.psd"),
    true # export with the color adjustments
  )
  #=> false
  # no file written

  Sketchup.active_model.materials[0].texture.write(
    UI.savepanel(CAPTION,TESTDIR,"psd_test_texture_write_false.psd"),
    false # not exported with the color adjustments
  )
  #=> false
  # writes 0 bytesize psd file
  # Issue #57

# Sketchup::View.write_image()
# Doc: No supported filetypes listed. (Examples show only png and jpg.)
# Doc: Return type has no explanation. Says only "(Boolean)". 
# File: Should not be writing empty files for unsupported filetypes.
  Sketchup.active_model.active_view.write_image(
    UI.savepanel(CAPTION,TESTDIR,"psd_test_view_write_image.psd")
  )
  #=> false
  # writes 0 bytesize psd file

IMPORT TESTS

TESTSOURCEDIR = "D:/DOCUMENTS/SketchUp/ImportTest/PSD"
IMPORTCAPTION = "Import psd test ..."

# Sketchup::Model.import()
# Doc: Return type has no explanation. Says only "(Boolean)". The method 
#   instance likely returns true immediately if filetype is supported,
#   and the imported object is attached to the cursor for placement by user.
#   If the file type is unsupported, false is returned.
#   (No exception raised. Nothing is imported.)
  Sketchup.active_model.import(
    UI.openpanel(IMPORTCAPTION,TESTSOURCEDIR,"*.psd")
  )
  #=> true
  #=> Works exactly like "File > Import ..." after file choice.

ISSUE BREAKDOWN

BUG (1): Should not be writing empty files for unsupported filetypes. It should be obvious from the report that many of the thumbnail and texture writing methods share core function(s) that are writing empty files when they shouldn't.

BUG (2): [Perhaps related to 1,] Is the strange aspect of Sketchup::Texture#write() that it only create the empty file when the 2nd argument is false (the default.)

BUG (3): Sketchup::ImageRep#save_file() exception ?

Perhaps should raise ArgumentError ("Unsupported file extension") instead of RuntimeError with a vague "failed to save file" message. ( See: Sketchup::Model#export() error handling for precedent.)

DOC (1): No supported filetypes listed for:

DOC (2): No return type documented at all:

Sketchup::ImageRep#save_file()

DOC (3): Return type has no explanation. Says only "(Boolean)":

DOC (4): Sketchup::Model#export() supported formats

"SketchUp Free" should be "SketchUp Make" or "non-Pro editions".
Separate non-Pro export formats from Pro. (It has been complained in the forum that it is not clear that IFC and PDF are Pro only.)

SketchUp / api-issue-tracker