Module namespace organization

🚀 Feature

Cleaner namespaces?

Right-now all(?) functional and class methods are available through the main module namespace. So when I write kornia. and hit tab I get all the things… this is good in some cases like for autocompletion, but end up being confusing in some (ie. later while reading code)

I like the higher submodule categorizations (augmentation,color,feature,filters etc) they make sense, but within each submodule there are inconsistencies. Below are some things I have noticed:

• Some modules have an F submodule some have functional and some just have the functional things on the main level. -> would be better to unite consistently. Imo functional is better and if wanted people can just import it as F.

• Some modules have higher modules as submodules(?) so something like k.augmentation.augmentation.F.functional.adjust_brightness ends up being valid and confusing (Not that you would write that but still 😕 )

• Some functions are not where you would expect them example: motion_blur is not in kornia.filters.blur but in kornia.filters.motion.motion_blur, In this case it is nice to have it in kornia.filters.motion_blur (or maybe kornia.filters.functional.motion_blur) (Docs have motion_blur under blur, maybe just version differences?)

  • Honestly filters and feature modules are a bit confusing. Example the gaussian_blur2d in kornia.feature.responses.gaussian_blur2d. The module name called responses vs detectors in docs.

• Some operations don’t have functional equivalents or vice versa (maybe intentionally? maybe just forgotten?)

Using v0.4.2 & looking at latest docs

Motivation

This might be more of a personal preference thing, idk. It makes it harder to see/find what functionality is there, especially when not familiar with the library. There is a lot of functionality in Kornia which I love ❤️ but would love it even more if it is organized a bit more.

Pitch

• Put all functional things under submodule.functional on the main level and on the subsubmodule level they can be higher. Example kornia.functional.rgb_to_bgr & kornia.color.rgb_to_bgr

Alternatives

Open to suggestions~ Would like to hear what everyone else thinks! Or explanations on the logic behind the current system.

[edgarriba]

@cceyda thanks for pointing this out. The trend we have been more or less following is to move everything to functionals except for the augmentations which we might want to promote their usage as modules to help with the optimization of the parameters.

The reason for having everything exposed to the top level is purely for convenience at the time to import the whole package (we started small 😃) What would change for example from kornia.functional.rgb_to_bgr to kornia.rgb_to_bgr ? I personally prefer the second.

The case for motion blur, I agree, feel free to send a PR fixing it. However, consider to raise a deprecation warning since at this point we have to make this kind of changes “slowly” giving beforehand feedback to the users. Regarding gaussian_blur2d, what version do you use ? I believe it has been existing to kornia.filters for a while.

We would love to work on cleaning the modules organization to make a more stable API. Do you use slack ? feel free to join us so that we can continue the discussion in there - here is the LINK

[edgarriba]

See kornia.augmentations as a small separated library on top of other kornia-core (we even had the discussion to create a separated repo for that). augmentation.apply_adjust_saturation and similar should be deprecated /cc @shijianjian I think already did some work on that. In this specific case we have been trying to promote something like this:

class RandomSaturation(AugmentationBase2D):
    def __init__(self, *args, **kwargs) -> None:
        super().__init__(*args, **kwargs)

    def generate_parameters(self, shape: torch.Size):
       return dict(saturation_factor=torch.rand(shape))

    def apply_transform(self, input: torch.Tensor, params: Dict[str, torch.Tensor]) -> torch.Tensor:
       return kornia.enhance.adjust_saturation(input, params['saturation_factor'])

I agree the we need better documentation and more examples.

NOTE: see some of the examples I’ve been adding https://github.com/kornia/kornia/pull/960/files#diff-e0d73d8ca93dbcc39aa641f369f03236fb9ab8b6d951a6770dadf15450656ecfR1418