STL Ready Image

stl-ready-image is a tool designed to convert 2D images into 3D printable STL files. It works by analyzing an input image, a specified layer height, and a target model size (in mm) to create a height map. This height map is then used to generate an STL file.

A primary use case is creating highly detailed, lithophane-like models that are designed to be illuminated from the left rather than being back-lit like traditional lithophanes.

When printing the generated STL files on an FDM printer, follow these best practices:

• Orientation: The heightmap should be oriented vertically (the STL file is generated with the correct orientation by default).
• Bed Adhesion: Using a brim is recommended.
• Infill: You can print the model with 0% infill.
• Z Seam: Set the Z seam alignment to the sharpest corner to prevent it from obstructing the image.

To use the graphical interface:

1. Download stl-ready-image.exe from the releases page.
2. Click Browse to select your input image and the destination folder for the generated STL.
3. Enter the desired Width and Height in mm. The tool automatically adjusts these values to maintain the original aspect ratio.
4. Enter the Layer Height you intend to use for 3D printing (default is 0.2 mm).
5. Click Generate STL. The resulting file will be named imagename.stl in your selected folder.

If you prefer to run the script via Python instead of using the standalone executable, you must first install the necessary dependencies using the provided requirements.txt file.

python -m pip install -r requirements.txt

The application is launched by executing the main.py script. It initializes a graphical user interface (GUI) that allows users to select an image, specify a folder for output, and enter dimensions (width, height, and layer height) to generate an STL model from a height map.

python src/main.py

Use save_stl to write a numpy-based mesh object to a file on disk.

Parameters:

• mesh (stl.mesh.Mesh): The mesh object to save.
• path (str): The file path where the .stl file will be created.

def save_stl(mesh, path):
    mesh.save(path)

The resize_img(img, cols, rows) function resizes the provided PIL Image to the specified cols and rows dimensions. It then returns the image data as a 2D list (list of lists) where each pixel value is normalized by dividing the original 0-255 value by 255, resulting in values in the range [0, 1].

# Example usage
# cols and rows are typically derived from auto_scale_img_values()
pixel_data = resize_img(img, 100, 100)

The get_height_map(pixels, cols, rows) function is the primary entry point for converting processed pixel data into a height map.

It follows this workflow:

1. Calculates the average pixel value across the entire image.
2. Processes each row using get_row_height_map(), which adjusts pixel values relative to the average.
3. Normalizes the resulting 2D list to the range [0, 1] using the normalize() function.

Input pixels should be a 2D list of values (typically from resize_img).

# pixels is the 2D list from resize_img()
height_map = get_height_map(pixels, cols, rows)

Use these functions to determine new dimensions while maintaining the original image's aspect ratio:

• calculate_height(img, width): Returns the calculated height as a string, rounded to 2 decimal places, based on a provided width.
• calculate_width(img, height): Returns the calculated width as a string, rounded to 2 decimal places, based on a provided height.

# Example usage
new_height = calculate_height(img, 800)
new_width = calculate_width(img, 600)

The normalize(pixels) function takes a 2D list of pixel values and scales them so that the minimum value in the entire set becomes 0 and the maximum value becomes 1. This is useful for ensuring height map data is within a standard range for STL generation.

# pixels is a 2D list of numeric values
norm_pixels = normalize(pixels)

The open_image(file) function prepares an image for processing by opening the specified file, converting it to grayscale ('L' mode), and increasing its contrast by a factor of 1.5 using ImageEnhance.Contrast. This is a prerequisite for generating consistent height maps from visual data.

from src.utils.image_processing import open_image

img = open_image('path/to/your/image.png')