FCBmpImport - macro to import black and white bmp images

Need help, or want to share a macro? Post here!
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
TheMarkster
Veteran
Posts: 5505
Joined: Thu Apr 05, 2018 1:53 am

FCBmpImport - macro to import black and white bmp images

Post by TheMarkster »

https://github.com/mwganson/fcbmpimport

FCBmpImport is a macro for importing black and white (1 bit per pixel) bmp images into FreeCAD as FreeCAD objects. These can be imported as Mesh Objects (requires OpenSCAD binary to be installed), Solids (based on Part workbench Wedge objects), Sketches, Wires, Faces, and Extruded. I have included fairly extensive documentation in the readme file on my github site.

The images must be in 1 bit per pixel bmp format, although the preview image feature will work in a number of other formats (but the actual import requires 1bpp bmp). A good tool for converting an image to that format is GIMP2. I have instructions for doing this in the readme, too.

In addition to being able to import images the macro also has a couple helper features that could prove useful in other contexts (besides importing images). One of them is the ability to select objects (can be faces, points, or edges) based upon an object already selected. The most recently selected object becomes a template, based on that object's zmin and zmax (or xmin/xmax or ymin/ymax) values in its bounding box. Other such objects matching that same zmin/zmax that are part of the larger object will be added to the selection. This can be useful for selecting a bunch of faces in the Path workbench preparatory to creating pocket paths from said faces. Could also be of use if you wish to select edges for fillet or chamfer operations.

I've also including some wire point editing tools for manpulating DWire objects. With these tools you can do things like select every odd vertex in a DWire object, move or cut the selected points, insert new points, etc. The purpose for these tools would be to smooth out or cleanup pixellated edges when importing lower resolution images (which we are unfortunately going to be limited to using due to performance issues when using higher resolution images) as wires or faces, but since they can be used on any DWire object you might (or might not) find them useful even if you don't import images with the macro.

My code isn't very 'pretty' or 'elegant', but I'm just a self-taught amateur hobbyist programmer. I am also relatively new to FreeCAD, Python, and Qt, so this project was as much about learning more about those as about creating a (hopefully) useful macro. I also wanted a way to import images for use with a little CNC engraving machine using FreeCAD, the idea being to import the image, setup the G-Code, and do the engraving. It works fairly well for this purpose, all things considered. I've learned a lot (though I am certainly no guru), and there are probably some things I would do a little bit differently the next time, and no doubt there are things that will need to be corrected, bugs fixed, etc. Virtually all of the testing that I have done with the macro has been using Windows 10 64 bit, and only very minimal testing using the linux appliance on the downloads page with Puppy Linux 7.5 64 bit (Xenial-based).
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: FCBmpImport - macro to import black and white bmp images

Post by yorik »

Impressive work, specially the documentation! It's not often that someone takes the time to write so nice docs about her/his own code :? ... Congrats!

Would you allow your macro to be added to the official collection? We're actually in the process of enabling macros that are hosted on github to be added too.. -> https://forum.freecadweb.org/viewtopic. ... 20#p234920
TheMarkster
Veteran
Posts: 5505
Joined: Thu Apr 05, 2018 1:53 am

Re: FCBmpImport - macro to import black and white bmp images

Post by TheMarkster »

Thanks. Yes, I would like to have it added. There is a pull request on github for it. https://github.com/FreeCAD/FreeCAD-macros/pull/15

Let me know if there's anything else I need to do.
User avatar
microelly2
Veteran
Posts: 4688
Joined: Tue Nov 12, 2013 4:06 pm
Contact:

Re: FCBmpImport - macro to import black and white bmp images

Post by microelly2 »

thank you for this macro with a lot of opportunities.
this is really a good start point to import and postprocess images.
I will test it and integrate it into my workflows next days.
TheMarkster
Veteran
Posts: 5505
Joined: Thu Apr 05, 2018 1:53 am

Re: FCBmpImport - macro to import black and white bmp images

Post by TheMarkster »

I added some more error checking in the wire point editing tools to ensure the user is trying to perform the various operations on DWire objects rather than other object types that are not supported. Latest version is now 2018.05.23.
mario52
Veteran
Posts: 4673
Joined: Wed May 16, 2012 2:13 pm

Re: FCBmpImport - macro to import black and white bmp images

Post by mario52 »

hi
congrat and thank you for this useful macro

mario
Maybe you need a special feature, go into Macros_recipes and Code_snippets, Topological_data_scripting.
My macros on Gist.github here complete macros Wiki and forum.
TheMarkster
Veteran
Posts: 5505
Joined: Thu Apr 05, 2018 1:53 am

Re: FCBmpImport - macro to import black and white bmp images

Post by TheMarkster »

Added new feature, latest version 2018.05.26:

right-click context menu for the Select button in the Wire Point Editing tools. Only menu item at this time is to make a new DWire object from the selected object.

The wire point editing tools require DWire objects, so it is necessary for some objects to create a new DWire object in order to use the tools. The original object is hidden and the new DWire object is created in its place. Tested (on Windows) with these Draft workbench objects:

Rectangle
Circle
Arc
Ellipse
ShapeString
Regular Polygon

For circle and ellipse types make sure property Make Face = False on the original object or else the creation of the new DWire object won't work.

Does not work on:

BSPline
Point
Line


Circle, Ellipse, and Arc objects must be discretized. Default Number parameter is 50, can be changed by modifying this in the defaults section of the source code:

DISCRETIZED_NUMBER=50


I also made the UI look better on Mac OS, but some features still not working.

Edit: as of version 2018.05.26b Make DWire now working with BSplines and Bezier curves and other objects with Make Face = True.
TheMarkster
Veteran
Posts: 5505
Joined: Thu Apr 05, 2018 1:53 am

Re: FCBmpImport - macro to import black and white bmp images

Post by TheMarkster »

I've added a few new features to the Select button right-click context menu.

Choose Make Arc from 3 Points to make an arc and replace existing structures of DWire object.
using_make_arc.png
using_make_arc.png (70.64 KiB) Viewed 4799 times
It says "Finished Shape", but obviously there's more work to be done on that particular shape. Make Arc can also be used on the other edges to replace them with gentler curves. You must select 3 points on the same Dwire object, and they can't be colinear. (But remember, you can always move one of the points very slightly and do it again.) Occasionally with Make Arc you will get an arc that has the start angle and end angles reversed. When that happens, just cancel and reverse the order in which you selected the 3 points, and try again. Occasionally the replace operation will go wrong and you end up losing most of the original object. Don't panic, just use the Select button context menu Undo (not FreeCAD's Undo) to restore it to where it was. This is usually because the points being replaced spanned across the last vertex back to vertex1. You can use Reorder Points to reset vertex1 to some other point and try again if that happens.

There is also a Make Line, Replace Existing function that works with colinear points. I probably should have called it Make Multiline, but anyways, it works very similarly to Make Arc except you can use any number of points (2+) and it will make the multiline along those points, replacing existing structures. This function, together with Make Arc, can be really useful to quickly smooth out the edges after importing low resolution pixellated images.

There is also now an Undo function in the context menu that can undo (usually) most of the Wire Point Editing operations as long as there's at least some remnant of the original DWire still remaining. Note: there is only one level of undo, so undo immediately if there's a problem before the undo buffer gets replaced with another operation.

Sometimes the replacement function can go wrong and you end up with your wires crossed. The Reverse Points feature can be used to uncross the wires when that happens, but it's probably better to just undo the operation and try going from the opposite direction or reordering the points so vertex1 is out of the way.

I still need to do more on getting it to work better on MacOS. That's next on the agenda for this macro.
TheMarkster
Veteran
Posts: 5505
Joined: Thu Apr 05, 2018 1:53 am

Re: FCBmpImport - macro to import black and white bmp images

Post by TheMarkster »

I added an animated gif to the github site showing use of the 2 latest features. I tried to post it here, but alas, it was too big. Here's a shorter version:
screencap4.gif
screencap4.gif (753.66 KiB) Viewed 4767 times

The offscreen activity is going to Edit menu -> Select all to select all the DWire objects in the document. The Select button context menu is brought up by right-clicking on it.

2 new features:

Apply Midpoints
Remove Colinear Points

I believe these are both game changers for this macro. Apply midpoints, for lack of a better name, basically takes all the sets of 2 consecutive points and replaces p1 with the midpoint between p1 and p2. What's the big deal? For imported wires from low res images this will greatly smooth out the pixellated edges. Running it a second time can sometimes refine it even more.

Remove Colinear Points reduces the complexity of the DWire object without sacrificing any of the image quality because it only removes those points that are colinear with the points before and after it. This operation should make future operations easier on FreeCAD because there won't be as many points, edges, faces to be dealt with. Boolean operations, like cuts and fusions, path operations, should all go faster because now the objects aren't as complex as before.
galou_breizh
Posts: 436
Joined: Wed Sep 15, 2010 9:38 am

Re: FCBmpImport - macro to import black and white bmp images

Post by galou_breizh »

I took the opportunity that Normand was talking about missing icons of the Image Workbench to introduce FCBmpImport there.
Post Reply