OP2MapImager Development

[Hooman]

It sounds like statically linking to FreeImage does not fit the bill with what you would be comfortable with. So in the meantime we can just leave it in DLL form (which I think we can do and license or not license the rest of the code as we see fit). This has the added benefit of being less work.

Actually, from what I found in my reading, apparently static linking versus dynamic linking has no impact on the licensing. Either which way, if you're using FreeImage, your project must be GPL.

I'm just looking for the code to remain available for other people to review, edit, and compile as they see fit without assuming responsibility for any perceived damages the source code or compiled application could cause.

Sounds like you would agree with MIT or BSD licensing. The two appear to be basically equivalent. That's also what I would choose for my code. Those licenses are very minimal, doing basically only what you're asking here.

However, that's not a compatible license for something that uses FreeImage.

Using the GPL license would also mean your code is free for others to review, edit, and compile. Though it slaps on the restriction that if third parties distribute the code, original or modified, source or compiled, they must also make their copy/modifications of the source code available, and slap on the same restriction for anyone using it.


For now it sounds like you can just release your project as GPL and not worry too much about it. It will still be open source. Though if we want to get formal about licensing, I should attach a license to my portion. I would likely choose either MIT or BSD based on what I read today. That would be compatible with making your project GPL.

If someone wants to look into removing the FreeImage dependency, we could look into re-releasing the software package in the future under a new more permissive license. Basically we can punt this problem down the road. Only you would be able to re-release your project under a different license though. If you disappear, your code would be locked to GPL.


Is the FreeImage dependency restricted to OP2MapImager, or is it a part of OP2Utility? If it's not part of OP2Utility, you can license OP2Utility with a more permissive compatible license such as MIT or BSD, and then make the OP2MapImager project GPL.

[Hooman]

Noticed that GitHub links to Choose A License.

The 3 options on the short list are MIT, Apache, and GPL, depending on how permissive/restrictive you want to be. They also have longer lists with more licenses to choose from.


If we wanted to have some fun with this, we could always choose the wtfpl.

(On second thought, let's not choose that license)

[Vagabond]

Yes, FreeImage is restricted to only the two files mentioned earlier which are both contained in OP2MapImager. OP2Archive and OP2Utility could certainly be placed under an MIT license with OP2MapImager maintaining the GPL license.

If we go that route, would that mean that both the OP2Utility MIT license and the FreeImage GPL license both need to be distributed with the final OP2MapImager executable?

I looked over the licenses a little. It seems that the MIT license is considerably more popular than the BSD license. So I would probably chose MIT over BSD since it would be more familiar. I am happy to use the MIT license for both OP2Archive and OP2Utility.

I attached a copy of the MIT license that came up when googling. Just to make sure we are on the same page to the exact wording.

On a related note, since I just copied and pasted the archive code Hooman wrote into the OP2Utility project, it has lost all of its history. While I don't think it is really needed from a programming perspective, it would have been nice to preserve it from an ownership perspective. Now it looks like to someone reviewing the history that I wrote everything when this is not that case. So, I apologize for doing that. Bad choice in retrospect. It might be possible to graft Hooman's history on VolDecompress from SVN into OP2Utility in Git??? If so it would fix my blunder.

-Brett

MIT LICENSE

Copyright <YEAR> <COPYRIGHT HOLDER>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

[leeor_net]

MIT is acceptable to me. I like it, BSD 3-clause simplified and Zlib license. I tend to use the zlib license for my work (basically, do what you want with it, just don't claim it as your own).

[Hooman]

If we go that route, would that mean that both the OP2Utility MIT license and the FreeImage GPL license both need to be distributed with the final OP2MapImager executable?

For the binary distribution, I'm a little unclear on the details. I don't know if you're required to include a copy of the MIT license with a binary distribution. Though it wouldn't be wrong to give proper attribution in a binary distribution, and I would encourage that for third party libraries. I believe the GPL is required to be either distributed alongside a binary, or have a way for the binary to output a copy of the GPL.

For the source code, yes, you should include both licenses, and it would need to be clear what sections are covered by each license. In particular, the MIT license would not apply to FreeImage or the project as a whole, while the GPL will apply to the whole project.

I looked over the licenses a little. It seems that the MIT license is considerably more popular than the BSD license. So I would probably chose MIT over BSD since it would be more familiar. I am happy to use the MIT license for both OP2Archive and OP2Utility.

Sounds like they are all nearly equivalent. I think due to the similarity, short lists will include only one of the three. That might result in one becoming more popular than the others.


Don't worry about the history of the project. I don't think it's that important. It's easy enough to discover, and a note can always be added about where it came from. To fix the history now would require rewriting history. If other people have cloned copies of the project, it would cause update issues.


The license you included is the one I'm thinking of.


As for the BSD license, there are 3 of them. The original 4-clause license, the new/modified 3-clause license, and the simplified 2-clause license.

Here are some licenses for reference:
MIT
zlib
BSD 2-clause
BSD 3-clause
(The BSD 4-clause license is considered by some to be restrictive, and not compatible with GPL. Didn't find a reference to it on the same site)
GPL-3.0
GPL-2.0

The GPL licenses are considerable longer than the others.

One difference I read noted about MIT, is the right to sub-license as the licencee, which is supposedly different from BSD and zlib.


I rather like the wording of zlib actually. It's very clear about what is required versus appreciated, and they are clear about source as opposed to binary. I think I still prefer MIT, but wish it was a little more explicit about those things.

[Vagabond]

I went ahead and added MIT license files to both OP2Utility and OP2Archive. Unfortunately, GitHub didn't recognize them! I must not have copied them exactly verbatim enough for GitHub to recognize it or perhaps it takes some time for a bot to review the repo and catalog it.

https://github.com/OutpostUniverse

I'll give it a day or so and then probably repost the OP2Archive zip file with the license included.

-Brett

[Hooman]

It might require a special filename, such as "LICENSE.txt".

[leeor_net]

I've been saving these as markdown files (.MD) and Github seems to pick that up well.

[Hooman]

Vagabond, have you tried experimenting with the various image scaling algorithms? The FreeImage_Rescale method takes an optional filter parameter, which defaults to FILTER_CATMULLROM. I wonder if FILTER_BOX might be appropriate, and if it would change the image quality or rescale speed.

[Vagabond]

Hooman,

Did you notice the bug in my current release before or after asking that question?

I'll try to post a newer version soon with the bug fixed. If you are looking to image an individual map right now, you have to read it in as ./eden03.map. using eden03.map will cause an error because the program cannot find the relative directory. I've already fixed it locally on my machine and will plan to push soon.

Anyways, to answer your question:

The deciding factor in how long a render takes is how many pixels must be placed onto the final canvas, not how the initial scaling of the tilesets is accomplished. This is because we are scaling tilesets first, and then applying them to a canvas to form the map.

Rendering maps to 4x4 pixels per tile averages 0.142 seconds, which I think is quick enough for this application?

If you ever wanted to render the maps for display in a GUI at 1x1 pixel per tile, it would average 0.075 seconds per map, which would probably be fast enough? The problem is that even at 1x1 pixels per map, a large map like survaxen at 512x256 tiles takes on average 0.233 seconds per map, which might be too long for a GUI application?

We could speed up rendering large batches of low pixels per tile by caching different scales of the tiles so they didn't have to rescale each time another render is taken. This has some side effects though if you are going to render say both stock tileset maps and Greenworld tileset maps in the same session, since they use the same name for wells. However, at 0.14 seconds average for the default setting, I'm pretty happy and am not sure the juice is worth the squeeze.

The caching would likely have minimal effect on rendering very large maps. I'm not sure the answer there for speeding it up, but survaxen at full size is about 58 megabytes, so I'm not sure how fast it should be expected to be created at either? I'm thinking slow should be expected though.

As for quality of the scaling, I've been very pleased with it. I'm not a graphics artist though. Do you or someone else feel like they could be better quality after being scaled? I don't mind if you want to experiment with different settings. We could even offer a switch on the console command for it, but it didn't seem worth it to me.

And the metrics for you. Using my computer and a stopwatch (so could be more accurate, but good enough for broad strokes). A release compilation without being attached to a debugger. Did not try to control background applications.

Rendering the 79 stock maps with the current release + Judgement Day and Fractured Alliance. All maps existing inside .VOL files expect the two non-stock maps:

1x1 pixels per tile, 5.93 seconds, 0.075 seconds per map,
4x4 pixels per tile, 11.24 seconds, 0.142 seconds per map
8x8 pixels per tile, 24.92 seconds, 0.315 seconds per map
16x16 pixels per tile, 1 minute, 24.56 seconds, 1.07 seconds per map
32x32 pixels per tile, 10 minutes, 46.88 seconds, 8.19 seconds per map

9 survaxen maps (512x256 tiles) at 1x1 pixels per tile, 2.10 seconds, .233 seconds per map

-Brett

[Hooman]

Did you notice the bug in my current release before or after asking that question?

Ehh, no. Being on Linux.... It was just a curious question.

In FreeImage, the Rescale function is:

Code: [Select]

FIBITMAP* FreeImage_Rescale(FIBITMAP *src, int dst_width, int dst_height, FREE_IMAGE_FILTER filter)

In your code, you're calling it without the last parameter, which defaults to FILTER_CATMULLROM. The available filters are:

Code: [Select]

FI_ENUM(FREE_IMAGE_FILTER) {
	FILTER_BOX		  = 0,	// Box, pulse, Fourier window, 1st order (constant) b-spline
	FILTER_BICUBIC	  = 1,	// Mitchell & Netravali's two-param cubic filter
	FILTER_BILINEAR   = 2,	// Bilinear filter
	FILTER_BSPLINE	  = 3,	// 4th order (cubic) b-spline
	FILTER_CATMULLROM = 4,	// Catmull-Rom spline, Overhauser spline
	FILTER_LANCZOS3	  = 5	// Lanczos3 filter
};

It seems the further down the list you go, the better the quality is supposed to be. It actually depends on a number of factors though, both about the source image, and the scale factor. In particular, if you scale down by more than 1/2, some algorithms can skip over source data entirely, which may be undesirable. Also, some of them may use surrounding pixels in the formula, which may not be desirable due to the tile nature of the source image. You could end up with pixels from an adjacent tile bleeding into a scaled down tile. For these reasons, I think the first option might actually be the most desirable for our application, as it should have a hard cutoff at tile boundaries, and not discard data when scaling significantly, but rather average all the data into the output. Further, the further down the list you go, the more the computational requirements tend to increase. Hence, for both speed and quality, it might might sense to try the first option. I suspect there will be no noticeable difference in either speed or quality, partly for the reasons you've stated, though I thought I'd ask if you've tried already.

We could speed up rendering large batches of low pixels per tile by caching different scales of the tiles so they didn't have to rescale each time another render is taken.

Yes, I was thinking of that. I was actually looking at the code wondering if you might have already done it.

This has some side effects though if you are going to render say both stock tileset maps and Greenworld tileset maps in the same session, since they use the same name for wells.

I had also thought of this too. If you include the VOL file as part of the path, as if it were a folder, it might solve the name issue. Given enough tilesets, it could create a memory issue, though I doubt that will ever become a problem. Could just have the user convert images in smaller batches, or have the rendering discard old cached items if the current map uses a different tileset.


Thanks for the timing info. It seems the large maps take a fairly significant portion of the time. Does that also hold for large 32x32 renders? I suspect there is a fair bit of overhead for each tile draw, beyond just copying the pixels. That may lower efficiency as tile sizes drop.

[Vagabond]

Quote
Did you notice the bug in my current release before or after asking that question?


Ehh, no. Being on Linux.... It was just a curious question.

Sorry, that was a bad attempt at a joke. More serious note though. I would be interested in knowing if you can run the OP2MapImager using Wine. If you take the time to run it and things work out, I'll annotate that it is Wine compatible in the documentation since we didn't make it to a full Linux build. Attached is a release build of Ver 2.0.1B. It contains the bugfix for the mentioned problem and a timer. (This should probably be 2.1.0 if I leave the timer in since it would be a new feature instead of just a bugfix now.)

I hardcoded the FILTER_BICUBIC scale filter and took renders of tutorial.map at 1, 4, 8, 16, and 32 pixels. I'll send you an email with those files and the same scale sizes using the FILTER_CATMULLROM. If you notice any diference, please let me know. I did notice the file sizes are different, so there are at least some minor differences in each file. Except the 32 pixel (unscaled) version is the exact same size regardless of filter. Files size is too large even if I dump the 32 pixel versions for the forum.

If you feel like the BICUBIC filter is producing better results, I'll switch the code over to it. Also, if it works on Wine and you want to test the different filters, let me know. I could put a switch in place for the scale filter in about an hour of work.

I also wrote a little timer using the chrono header. That way if you keep wanting to test more times, it is easier than manually timing them. It times from sorting the arguments to posting the initial complete message. So you are getting the entire time of execution of the application, not just the creation of the scaled image. However, if you are timing a decent number of maps at once, it should be insignificant either way.

Lastly, I timed a batch of 9 survaxen maps at 32x32 tile pixel scale (full size). It took 5 minutes, 34.48 seconds. or 37.16 seconds per map.

-Brett

[Hooman]

Huh, I see now I was using ridiculous colloquial language. I would actually be most interested in FILTER_BOX. (The zeroth option). 

Hmm, 30 seconds to draw a map seems quite substantial. I suspect there is room for improvement. Would probably need to instrument the code though to know where the time is being spent. It could be the drawing, though it could just as easily be moving large chunks of data to disk, or some kind of memory management issue. At any rate, it's not a problem. I just get easily excited by the idea of optimizing things.

[Hooman]

I got your email. I can see no discernible difference between FILTER_BOX and FILTER_CATMULLROM. I did notice a slight difference in file size, so something changed, just nothing I can detect visually.

What about time? Was there any change in processing time between the two filters?

[Vagabond]

Hooman,

Sorry it took a while to do. See data below. It does look like FILTER_BOX was faster on average for all 3 sizes tested then CATMULLROM. I guess a larger sample would be helpful to know for sure though.

-Brett


FILTER_BOX Runs

Scale: 1x1 pixel
7.44693
4.9601
5.7744
5.46432
Avg: 5.91

Scale: 4x4 pixels
11.4588 seconds
11.5282
11.4202
Avg: 11.47

Scale: 8x8 pixels
29.3788
27.9524
22.6675
Avg: 26.67

CATMULLROM Runs:

Scale: 1x1 pixel
5.15449
7.3895
6.0059
AVG: 6.18

Scale: 4x4 pixels
12.6625
13.1311
12.6421
AVG: 12.81

Scale: 8x8 pixels
23.994
36.9479
25.899
AVG: 28.95

[Hooman]

Hmm, it's tempting to suggest using FILTER_BOX as the default then.

Though looking at the numbers, there seems to be quite a bit of variance. The ranges overlap quite substantially. That does make it more difficult to draw hard conclusions.

Any idea why there was so much variance between the runs? Were you doing other things on the computer while waiting for the test runs to finish? (For a 10 minute run, I probably would be) 

Of course this may not be an important task to pursue. I think the main takeaway is that it really doesn't matter which scaling algorithm is used, the results are essentially the same.