The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CAD-Mesh3D-0.006001
River stage zero No dependents
1 ++
/ CAD::Mesh3D::STL

NAME

CAD::Mesh3D::STL - Used by CAD::Mesh3D to provide the STL format-specific functionality

SYNOPSIS

 use CAD::Mesh3D qw(+STL :create :formats);
 my $vect = createVertex();
 my $tri  = createFacet($v1, $v2, $v3);
 my $mesh = createMesh();
 $mesh->addToMesh($tri);
 ...
 $mesh->output(STL => $filehandle_or_filename, $ascii_or_binary);

DESCRIPTION

This module is used by CAD::Mesh3D to provide the STL format-specific functionality, including saving Meshes as STL files, or loading a Meshes from STL files.

STL ("stereolithography") files are a CAD format used as inputs in the 3D printing process.

The module supports either ASCII (plain-text) or binary (encoded) STL files.

enableFormat

You need to tell CAD::Mesh3D where to find this STL module. You can either specify +STL when you use CAD::Mesh3D:

 use CAD::Mesh3D qw(+STL :create :formats);

Or you can independently enable the STL format sometime later:

 use CAD::Mesh3D qw(:create :formats);
 enableFormat( 'STL' );

FILE OUTPUT

output

outputStl

To output your Mesh using the STL format, you should use CAD::Mesh3D's output() wrapper method. You can also call it as a function, which is included in the :formats import tag.

 use CAD::Mesh3D qw/+STL :formats/;
 $mesh->output(STL => $file, $asc);
 # or
 output($mesh, STL => $file, $asc);

The wrapper will call the CAD::Mesh3D::STL::outputStl() function internally, but makes it easy to keep your code compatible with other 3d-file formats.

If you insist on calling the STL function directly, it is possible, but not recommended, to call

 CAD::Mesh3D::STL::outputStl($mesh, $file, $asc);

The $file argument is either an already-opened filehandle, or the name of the file (if the full path is not specified, it will default to your script's directory), or "STDOUT" or "STDERR" to direct the output to the standard handles.

The $asc argument determines whether to use STL's ASCII mode: a non-zero numeric value, or the case-insensitive text "ASCII" or "ASC" will select ASCII mode; a missing or undefined $asc argument, or a zero value or empty string, or the case-insensitive text "BINARY" or "BIN" will select BINARY mode; if the argument contains a string other than those mentioned, outputStl() will cause the script to die.

FILE INPUT

input

inputStl

To input your Mesh from an STL file, you should use CAD::Mesh3D's input() wrapper function, which is included in the :formats import tag.

 use CAD::Mesh3D qw/+STL :formats/;
 my $mesh = input(STL => $file, $mode);
 my $mesh2= input(STL => $file);        # will determine ascii/binary based on file contents

The wrapper will call the CAD::Mesh3D::STL::inputStl() function internally, but makes it easy to keep your code compatible with other 3d-file formats.

If you insist on calling the STL function directly, it is possible, but not recommended, to call

 my $mesh = CAD::Mesh3D::STL::inputStl($file, $mode);

The $file argument is either an already-opened filehandle, or the name of the file (if the full path is not specified, it will default to your script's directory), or "STDIN" to receive the input from the standard input handle.

The $mode argument determines whether to use STL's ASCII mode: The case-insensitive text "ASCII" or "ASC" will select ASCII mode. The case-insensitive text "BINARY" or "BIN" will select BINARY mode. If the argument contains a string other than those mentioned, inputStl() will cause the script to die. On a missing or undefined $mode argument, or empty string, will cause input() to try to determine if it's ASCII or BINARY; input() will die if it cannot determine the file's mode automatically.

Caveat: When using an in-memory filehandle, you must explicitly define the $mode option, otherwise input() will die. (In-memory filehandles are not common. See open, search for "in-memory file", to find a little more about them. It is not likely you will require such a situation, but with explicit $mode, they will work.)

SEE ALSO

  • CAD::Format::STL - This is the backend used by CAD::Mesh3D::STL, which handles them actual parsing and writing of the STL files.

KNOWN ISSUES

CAD::Format::STL binary Windows bug

There is a known bug in CAD::Format::STL v0.2.1, which on Windows systems will cause binary STL files which happen to have the 0x0D byte to corrupt the data on output or input. Most binary STL files will work just fine; but there are a non-trivial number of floating-point values in the STL which include the 0x0D byte. There is a test for this in the xt\ author-tests of the CAD-Mesh3D distribution.

If your copy of CAD::Format::STL is affected by this bug, there is an easy patch, which you can manually add by editing your installed CAD\Format\STL.pm: near line 423, after the error checking in sub _write_binary, add the line binmode $fh; as the fourth line of code in that sub. Similarly, near line 348, add the line binmode $fh; as the third line of code inside the sub _read_binary.

The author of CAD::Format::STL has been notified, both through the issue tracker, and responded to requests to fix the bug. Hopefully, when the author has time, a new version of CAD::Format::STL will be released with the bug fixed. Until then, patching the module is the best workaround. A patched copy of v0.2.1.001 is available through this github link.

AUTHOR

Peter C. Jones <petercj AT cpan DOT org>

COPYRIGHT

Copyright (C) 2017,2018,2019,2020,2021 Peter C. Jones

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.