eneroth3 / sketchup-community-lib

Unoffical standard library for SketchUp Ruby extensions

SketchUp Community Library (Beta)

WIP

This project is at an early stage and these project outlines should be seen as a draft.

Intent/Scope

The purpose of this library is to:

• prevent developers from reinventing the wheel,
• being long-lived (no fancy front-end web frameworks that are obsolete next Tuesday, please) and
• encourage community members to share knowledge and have fun together!

This should be achieved through:

• simplicity,
• generality and
• consistency.

This library should be easy to grasp and use for new developers, while still being useful for advanced developers.

To prevent the library from being bloated with functionality, try to make your additions as generic as possible and save specific implementations for your own code base. For instance this library has a method for changing the axes of a ComponentDefinition, but if you want to, say, center the axes at the bottom of the BoundingBox, the code for defining the new axes placement will have to be in your own extension/library.

If you have found a way to mimic SketchUp's native face shading, created your own solid operations or creates some other rather specific functionality that is probably better suited as a separate library, but could be dependent on this one.

If you however have a snippet that is too simple to be published as an individual library and almost generic enough to fit into the API itself, this is the place for it.

Supported SU versions

No effort should be made to make the library support versions older than SketchUp 2014 (Ruby 2.0.0). Code readability, such as using the &:-idion, matters more than supporting ancient versions. SU 2014 is also the oldest version supporting TestUp2.

Individual methods doesn't have to support SU 2014, e.g. methods related to API features added in a later version, but their documentation must in that case state what the oldest supported version is.

Usage

The library is designed to be placed in the directory of each extension using it. For simplicity's and usability's sake it is not intended to be a standalone extension or in other ways be shared between extensions.

There are three ways to use this library for your own extensions.

Copy and Paste Code

Ugly but straightforward. When just one method or two are needed this is the simplest approach.

Manual Installation

Simple but tedious in the long run.

1. Copy the modules you need from modules/ into your own extension's directory, e.g. my_extension/vendor/c-lib/. Make sure all required dependencies are copied.
2. Replace wrapping module SkippyLib with that of your own extension, e.g. MyName::MyExtension.
3. Replace modules/ in require calls (if any) to point to your own extension's copy of the files, e.g. my_extension/vendor/c-lib/.
4. Require the files you need from your own code.

Automatic Installation with Skippy

Automation, yay!

1. Install Skippy. 2. Follow Skippy's instructions to set up a new project, install this library and use the module you need. 3. Require the files you need from your own code.

As of 2018-03-26 in a pre-release state and not recommended.

Contribute

1. Read and understand Intent/Scope.
2. Read and understand below guidelines.
3. Create your own fork of this project.
4. Create a new branch for your addition.
5. Do the thing!
6. If the master branch has been updated since you forked, merge master into your development branch. This simplifies testing and merging for the maintainer of this project.
7. Make a pull request.

To load all modules, e.g. for testing, load tools/loader.rb.

Guidelines

• Follow the Ruby Style Guide, with the modifications defined by .rubocop.yml.
  • Use Rubocop-SketchUp and make sure your code passes with no offenses.
• If a method could have been an instance method its first argument must be the object that would have been self. For instance LPoint.between?(point, boundary_a, boundary_b) should have the point being checked first, not between the other arguments. Code consistency is more important than non-generalizable logic.
• Code comments should tell why the code does what it does, never what it does. That should be obvious from the code itself.
• Document with YARD.
• KISS (keep it simple, stupid).
• Consistency! Consistency! Consistency!

sketchup-community-lib's Issues

Optionally keep flip in remove_scaling

Sometimes you want to reset scaling to garuantee an object's proportions, but still allow it to be flipped. It would be useful if Transformation.remove_scaling took an optional argument for stay_flipped (=false).

Menu and Command validation excluding Mac

Validation procs for menus and commands (toolbars) aren't reguarly called by SketchUp on Mac, resulting in falsely disabled entries. A method that only adds the proc on Windows, and ignore it on Mac, could be useful to isolate this hack from the business code.

If SketchUp on Mac is corrected the method in this library could be updated to add the proc in supported SU versions, and not in the older ones.

Specify library scope

When originally setting up a project scope I didn't know about Skippy's abilities to only install/use the desired modules rather than the full library. With this ability the risk of bloating extensions and scaring away users that just want a handful of features from the lib decreases.

Currently the Readme states specific features such as mimicking SketchUp's face shading and performing solid operations is outside the scope of the library. Maybe it isn't?

This library also largely overlaps with tt-lib. What are the differences and what benefits do the different libs have (or should have) in different situations.

Bugsplat from DefinitionList.remove and undo

SketchUp/api-issue-tracker/issues/75

This affects this library's LComponentDefinition.erase method, as it uses the native method for SU2018 and later. For now use the hack for earlier versions in SU 2018 too, but perhaps use native method in SU2019 if fixed then.

Camera Module

A LCamera module with a number of method could be added to the library.

Some examples are:

• vertical_fov (dependent on Camera#fov_is_height?)
• vertical_fov=
• horizontal_fov
• horizontal_fov=
• Toggling locked aspect ratio (also toggles fiv_is_height?) without changing view
• 35 mm equivalent focal length
• camera matrix getter for whole drawing area
• camera matrix getter excluding gray bars (from locked aspect ratio)

35 mm equivalent focal length can be implemented as:

# Get 35 mm equivalent focal length in mm.
#
# 35 mm equivalent focal length is a measurement for angle of view, originated
# in physical film.
#
# While Camera#focal_length returns different values depending on the
# image_width value, this method only depends on fov (field of view).
#
# See Camera.fov_is_height to determine if vertical or horizontal fov is
# used for defining focal_length_35.
#
# @return [Float]
def focal_length_35
  camera = Sketchup.active_model.active_view.camera

  # 36 mm is the width of a frame in standard 35 mm film. 35 mm is the height,
  # film transport included (the frame height is 24 mm).
  36.0 / (2 * Math.tan(camera.fov.degrees / 2))
end

# Set 35 mm equivalent focal length in mm.
#
# 35 mm equivalent focal length is a measurement for angle of view, originated
# in physical film.
#
# While Camera#focal_length= sets different fov values depending on the
# image_width value, this method only depends on passed focal_length_35.
#
# See Camera.fov_is_height to determine if vertical or horizontal fov is
# used for defining focal_length_35.
#
# @param focal_length_35 [Float]
def focal_length_35=(focal_length_35)
  camera = Sketchup.active_model.active_view.camera
  # 36 mm is the width of a frame in standard 35 mm film. 35 mm is the height,
  # film transport included (the frame height is 24 mm).
  camera.fov = 2 * Math.atan(36.0 / (2 * focal_length_35)).radians
end

Rename root namespace

Once Skippy supports a library namespace other than SkippyLib the root namespace of this project should be changed to something more explanatory, e.g. CommunityLib or CLib.

thomthom/skippy#19